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 | |
|
|
assert_error class (Exception)
Runs the block and ensures that it raises the correct Exception. Useful for asserting that an Exception will be raised. You may specify the particular Exception class, which defaults to Exception
.
Introduced in v3.0
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
assert_not arg (anything)
Raises an exception if the argument is not either nil or false.
Introduced in v3.3
# Example 1 | |
|
|
# Example 2 | |
|
|
assert_not_equal arg1 (anything), arg2 (anything)
Raises an exception if both arguments are qual.
Introduced in v3.3
# Example 1 | |
|
|
# Example 2 | |
|
|
assert_similar arg1 (anything), arg2 (anything)
Raises an exception if both arguments aren’t similar.
Currently similarity is only defined for numbers - all other types are compared for equality with assert_equal.
Useful for testing in cases where floating point imprecision stops you from being able to use assert_equal
.
Introduced in v3.0
# Example 1 | |
|
|
# Example 2 | |
|
|
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.
at
is just-in-time scheduling using multiple isolated threads. See time_warp
for ahead-of-time scheduling within the current thread.
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 | |
|
|
buffer symbol (name), number (duration)
Initialise or return a named buffer with a specific duration (defaults to 8 beats). Useful for working with the :record
FX. If the buffer is requested with a different duration, then a new buffer will be initialised and the old one recycled.
Introduced in v3.0
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
choose list (array)
Choose an element at random from a list (array).
If no arguments are given, will return a lambda function which when called takes an argument which will be a list to be chosen from. This is useful for choosing random onset:
vals for samples
Always returns a single element (or nil)
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
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
invert: |
Apply the specified num inversions to chord. See the fn |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
# Example 8 | |
|
|
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 | |
|
|
clear ()
All settings such as the current synth, BPM, random stream and tick values will be reset to their defaults. Consider using reset
to reset all these values to those inherited from the parent thread.
Introduced in v2.11
# 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.
If no synth to control is specified, then the last synth triggered by the current (or parent) thread will be controlled - see example below.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
# Example 8 | |
|
|
# Example 9 | |
|
|
# Example 10 | |
|
|
# Example 11 | |
|
|
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
. The values of the opts must be immutable. Currently numbers, symbols, booleans, nil and frozen strings, or vectors/rings/frozen arrays/maps of immutable values 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_midi_defaults
Returns the current MIDI defaults. This is a map of opt names to values
This can be set via the fns use_midi_defaults
, with_midi_defaults
, use_merged_midi_defaults
and with_merged_midi_defaults
.
Introduced in v3.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_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 values.
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_time
Returns the current logical time. This is a ‘wall-clock’ time which should typically be pretty similar to Time.now but quantised to a nearby sleep point in the thread. May be quite different to Time.now within a time_warp!
Unlike Time.now
, Multiple calls to current_time
with no interleaved calls to sleep
or sync
will return the same value.
Introduced in v3.0
# Example 1 | |
|
|
# Example 2 | |
|
|
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/string/number and resolves it to a midi note. The degree can be either a decimal number or a roman numeral (if it’s a string or symbol), and may optionally be prefixed an augmentation (a
/d
for an augmented/diminished interval, aa
/dd
for double augmented/diminished or p
for a perfect (unchanged) interval).
Introduced in v2.1
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
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 | |
|
|
eval_file filename (path)
Reads the full contents of the file with path
and executes within the current thread like a function call.
Introduced in v3.2
# Example 1 | |
|
|
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
get time_state_key (default)
Retrieve information from Time State set prior to the current time from either the current or any other thread. If called multiple times will always return the same value unless a call to sleep
, sync
, set
or cue
is interleaved. Also, calls to get
will always return the same value across Runs for deterministic behaviour - which means you may safely use it in your compositions for repeatable music. If no value is stored with the relevant key, will return nil
.
May be used within a time_warp
to retrieve past events. If in a time warp, get
can not be called from a future position. Does not advance time.
Introduced in v3.0
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
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 | |
|
|
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 steps elements. Steps defaults to 4
. 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_audio name (symbol)
Create a named synthesiser which works similar to play
, sample
or synth
. Rather than synthesising the sound mathematically or playing back recorded audio, it streams audio live from your sound card.
However, unlike play
, sample
and synth
, which allow multiple similar synths to play at the same time (i.e. a chord) only one live_audio
synth of a given name may exist in the system at any one time. This is similar to live_loop
where only one live loop of each name may exist at any one time. See examples for further information.
An additional difference is that live_audio
will create an infinitely long synth rather than be timed to an envelope like the standard synth
and sample
synths. This is particularly suitable for working with continuous incoming audio streams where the source of the audio is unknown (for example, it may be a guitar, an analog synth or an electronic violin). If the source is continuous, then it may not be suited to being stitched together by successive enveloped calls to something like: synth :sound_in, attack: 0, sustain: 4, release: 0
. If we were to live_loop
this with a sleep 4
to match the sustain duration, we would get something that emulated a continuous stream, but for certain inputs you’ll hear clicking at the seams between each successive call to synth
where the final part of the audio signal from the previous synth doesn’t precisely match up with the start of the signal in the next synth due to very minor timing differences.
Another important feature of live_audio
is that it will automatically move an existing live_audio
synth into the current FX context. This means you can live code the FX chain around the live stream and it will update automatically. See examples.
To stop a live_audio
synth, use the :stop
arg: live_audio :foo, :stop
.
.
Introduced in v3.0
input: |
The audio card input to read audio from. |
stereo: |
If set to truthy value (true, 1) will read from two consecutive audio card inputs. |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
live_loop name (symbol)
Loop the do/end block forever. However, unlike a basic loop, a live_loop has two special properties. Firstly it runs in a thread - so you can have any number of live loops running at the same time (concurrently). Secondly, you can change the behaviour of a live loop whilst it is still running without needing to stop it. Live loops are therefore the secret to live coding with Sonic Pi.
As live loops are excecuted within a named in_thread, they behave similarly. See the in_thread documentation for all the details. However, it’s worth mentioning a few important points here. Firstly, only one live loop with a given name can run at any one time. Therefore, if you define two or more live_loop
s called :foo
only one will be running. Another important aspect of live_loop
s is that they manage their own thread locals set with the use_*
and with_*
fns. This means that each live_loop
can have its own separate default synth, BPM and sample defaults. When a live_loop
is first created, it inherits the thread locals from the parent thread, but once it has started, the only way to change them is by re-defining the do/end body of the live_loop
. See the examples below for details. Finally, as mentioned above, provided their names are different, you may have many live_loop
s executing at once.
A typical way of live coding with live loops is to define a number of them in a buffer, hit Run to start them and then to modify their do/end blocks and then hit Run again. This will not create any more thread, but instead just modify the behaviour of the existing threads. The changes will not happen immediately. Instead, they will only happen the next time round the loop. This is because the behaviour of each live loop is implemented with a standard function. When a live loop is updated, the function definition is also updated. Each time round the live loop, the function is called, so the new behviour is only observed next time round the loop.
Also sends a cue
with the same name each time the live_loop
repeats. This may be used to sync
with other threads and live_loop
s.
If the live_loop
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). This allows you to ‘thread’ values across loops.
Finally, 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 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
# Example 8 | |
|
|
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
, .ogg
, .oga
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)
Given a directory containing multiple .wav
, .wave
, .aif
, .aiff
, .ogg
, .oga
or .flac
files, pre-loads all the samples into memory.
You may also specify the same set of source and filter pre-args available to sample
itself. load_sample
will load all matching samples (not just the sample sample
would play given the same opts) - see sample
’s docs for more information.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
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 and FX -> 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 | |
|
|
# Example 5 | |
|
|
loop ()
Given a do/end block, repeats it forever. Note that once the program enters the loop - it will not move on but will instead stay within the loop. Plain loops like this are like black holes - instead of sucking in the light they suck in the program.
The loop must either sleep
or sync
each time round otherwise it will stop and throw an error. This is to stop the loop from spinning out of control and locking the system.
For a more powerful, flexible loop built for live coding see live_loop
.
Introduced in v2.0
# Example 1 | |
|
|
map list (array)
Create a new immutable key/value map from args.
Introduced in v2.11
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
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 note (number)
Sends a MIDI note on event to all connected MIDI devices and all channels and then after sustain beats sends a MIDI note off event. Ensures MIDI trigger is synchronised with standard calls to play and sample. Co-operates completely with Sonic Pi’s timing system including time_warp
.
If note
is specified as :off
then all notes will be turned off (same as midi_all_notes_off
).
Introduced in v3.0
sustain: |
Duration of note event in beats |
vel: |
Velocity of note as a MIDI number |
on: |
If specified and false/nil/0 will stop the midi on/off messages from being sent out. (Ensures all opts are evaluated in this call to |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
midi_all_notes_off
Sends a MIDI all notes off message to all connected MIDI devices. on all channels. Use the port:
and channel:
opts to restrict which MIDI ports and channels are used.
When an All Notes Off event is received, all oscillators will turn off.
MIDI 1.0 Specification - Channel Mode Messages - All Notes Off
Introduced in v3.0
channel: |
Channel to send the all notes off message to |
port: |
MIDI port to send to |
on: |
If specified and false/nil/0 will stop the midi all notes off message from being sent out. (Ensures all opts are evaluated in this call to |
# Example 1 | |
|
|
# Example 2 | |
|
|
midi_cc control_num (midi), value (midi)
Sends a MIDI control change message to all connected devices on all channels. Use the port:
and channel:
opts to restrict which MIDI ports and channels are used.
Control number and control value can be passed as a note such as :e3
and decimal values will be rounded down or up to the nearest whole number - so values between 3.5 and 4 will be rounded up to 4 and values between 3.49999… and 3 will be rounded down to 3.
You may also optionally pass the control value as a floating point value between 0 and 1 such as 0.2 or 0.785 (which will be mapped to MIDI values between 0 and 127) using the val_f:
opt.
MIDI 1.0 Specification - Channel Voice Messages - Control change
Introduced in v3.0
channel: |
Channel(s) to send to |
port: |
MIDI port(s) to send to |
value: |
Control value as a MIDI number. |
val_f: |
Control value as a value between 0 and 1 (will be converted to a MIDI value) |
on: |
If specified and false/nil/0 will stop the midi cc message from being sent out. (Ensures all opts are evaluated in this call to |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
midi_channel_pressure val (midi)
Sends a MIDI channel pressure (aftertouch) message to all connected devices on all channels. Use the port:
and channel:
opts to restrict which MIDI ports and channels are used.
The pressure value can be passed as a note such as :e3
and decimal values will be rounded down or up to the nearest whole number - so values between 3.5 and 4 will be rounded up to 4 and values between 3.49999… and 3 will be rounded down to 3.
You may also optionally pass the pressure value as a floating point value between 0 and 1 such as 0.2 or 0.785 (which will be mapped to MIDI values between 0 and 127) using the val_f:
opt.
MIDI 1.0 Specification - Channel Voice Messages - Channel Pressure (Aftertouch)
Introduced in v3.0
channel: |
Channel(s) to send to |
port: |
MIDI port(s) to send to |
value: |
Pressure value as a MIDI number. |
val_f: |
Pressure value as a value between 0 and 1 (will be converted to a MIDI value) |
on: |
If specified and false/nil/0 will stop the midi channel pressure message from being sent out. (Ensures all opts are evaluated in this call to |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
midi_clock_beat duration (beats)
Sends enough MIDI clock ticks for one beat to all connected MIDI devices. Use the port:
opt to restrict which MIDI ports are used.
The MIDI specification requires 24 clock tick events to be sent per beat. These can either be sent manually using midi_clock_tick
or all 24 can be scheduled in one go using this fn. midi_clock_beat
will therefore schedule for 24 clock ticks to be sent linearly spread over duration beats. This fn will automatically take into account the current BPM and any time_warp
s.
Introduced in v3.0
port: |
MIDI port to send to |
on: |
If specified and false/nil/0 will stop the midi clock tick messages from being sent out. (Ensures all opts are evaluated in this call to |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
midi_clock_tick ()
Sends a MIDI clock tick message to all connected devices on all channels. Use the port:
and channel:
opts to restrict which MIDI ports and channels are used.
Typical MIDI devices expect the clock to send 24 ticks per quarter note (typically a beat). See midi_clock_beat
for a simple way of sending all the ticks for a given beat.
MIDI 1.0 Specification - System Real-Time Messages - Timing Clock
Introduced in v3.0
port: |
MIDI port to send to |
on: |
If specified and false/nil/0 will stop the midi clock tick message from being sent out. (Ensures all opts are evaluated in this call to |
# Example 1 | |
|
|
midi_continue ()
Sends the MIDI continue system message to all connected MIDI devices on all ports. Use the port:
opt to restrict which MIDI ports are used.
Upon receiving the MIDI continue event, the MIDI device(s) will continue at the point the sequence was stopped.
MIDI 1.0 Specification - System Real-Time Messages - Continue
Introduced in v3.0
port: |
MIDI Port(s) to send the continue message to |
# Example 1 | |
|
|
midi_local_control_off
Sends a MIDI local control off message to all connected devices on all channels. Use the port:
and channel:
opts to restrict which MIDI ports and channels are used.
All devices on a given channel will respond only to data received over MIDI. Played data, etc. will be ignored. See midi_local_control_on
to enable local control.
MIDI 1.0 Specification - Channel Mode Messages - Local Control Off
Introduced in v3.0
channel: |
Channel to send the local control off message to |
port: |
MIDI port to send to |
on: |
If specified and false/nil/0 will stop the midi local control off message from being sent out. (Ensures all opts are evaluated in this call to |
# Example 1 | |
|
|
# Example 2 | |
|
|
midi_local_control_on
Sends a MIDI local control on message to all connected devices on all channels. Use the port:
and channel:
opts to restrict which MIDI ports and channels are used.
All devices on a given channel will respond both to data received over MIDI and played data, etc. See midi_local_control_off
to disable local control.
MIDI 1.0 Specification - Channel Mode Messages - Local Control On
Introduced in v3.0
channel: |
Channel to send the local control on message to |
port: |
MIDI port to send to |
on: |
If specified and false/nil/0 will stop the midi local control on message from being sent out. (Ensures all opts are evaluated in this call to |
# Example 1 | |
|
|
# Example 2 | |
|
|
midi_mode mode (mode_keyword)
Sends the Omni/Mono/Poly MIDI mode message to all connected MIDI devices on all channels. Use the port:
and channel:
opts to restrict which MIDI ports and channels are used.
Valid modes are:
:omni_off - Omni Mode Off :omni_on - Omni Mode On :mono - Mono Mode On (Poly Off). Set num_chans: to be the number of channels to use (Omni Off) or 0 (Omni On). Default for num_chans: is 16. :poly - Poly Mode On (Mono Off)
Note that this fn also includes the behaviour of midi_all_notes_off
.
[MIDI 1.0 Specification - Channel Mode Messages - Omni Mode Off | Omni Mode On | Mono Mode On (Poly Off) | Poly Mode On](https://www.midi.org/specifications/item/table-1-summary-of-midi-message) |
Introduced in v3.0
channel: |
Channel to send the MIDI mode message to |
port: |
MIDI port to send to |
mode: |
Mode keyword - one of :omni_off, :omni_on, :mono or :poly |
num_chans: |
Used in mono mode only - Number of channels (defaults to 16) |
on: |
If specified and false/nil/0 will stop the midi local control off message from being sent out. (Ensures all opts are evaluated in this call to |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
midi_note_off note (midi), release_velocity (midi)
Sends the MIDI note off message to all connected devices on all channels. Use the port:
and channel:
opts to restrict which MIDI ports and channels are used.
Note and release velocity values can be passed as a note symbol such as :e3
or a number. Decimal values will be rounded down or up to the nearest whole number - so values between 3.5 and 4 will be rounded up to 4 and values between 3.49999… and 3 will be rounded down to 3. These values will also be clipped within the range 0->127 so all values lower then 0 will be increased to 0 and all values greater than 127 will be reduced to 127.
The release_velocity
param may be omitted - in which case it will default to 127 unless you supply it as a named opt via the keys velocity:
or vel_f:
.
You may also optionally pass the release velocity value as a floating point value between 0 and 1 such as 0.2 or 0.785 (which will be mapped to MIDI values between 0 and 127) using the vel_f:
opt.
MIDI 1.0 Specification - Channel Voice Messages - Note off event
Introduced in v3.0
channel: |
MIDI channel(s) to send event on as a number or list of numbers. |
port: |
MIDI port(s) to send to as a string or list of strings. |
velocity: |
Release velocity as a MIDI number. |
vel_f: |
Release velocity as a value between 0 and 1 (will be converted to a MIDI velocity) |
on: |
If specified and false/nil/0 will stop the midi note off message from being sent out. (Ensures all opts are evaluated in this call to |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
# Example 8 | |
|
|
# Example 9 | |
|
|
midi_note_on note (midi), velocity (midi)
Sends a MIDI Note On Event to all connected devices on all channels. Use the port:
and channel:
opts to indepently restrict which MIDI ports and channels are used.
Note and velocity values can be passed as a note symbol such as :e3
or a MIDI number such as 52. Decimal values will be rounded down or up to the nearest whole number - so values between 3.5 and 4 will be rounded up to 4 and values between 3.49999… and 3 will be rounded down to 3. These values will also be clipped within the range 0->127 so all values lower than 0 will be increased to 0 and all values greater than 127 will be reduced to 127.
The velocity
param may be omitted - in which case it will default to 127 unless you supply it as an opt via the keys velocity:
or vel_f:
.
You may also optionally pass the velocity value as a floating point value between 0 and 1 such as 0.2 or 0.785 (which will be linearly mapped to MIDI values between 0 and 127) using the vel_f: opt.
MIDI 1.0 Specification - Channel Voice Messages - Note on event
Introduced in v3.0
channel: |
MIDI channel(s) to send event on |
port: |
MIDI port(s) to send to |
velocity: |
Note velocity as a MIDI number. |
vel_f: |
Velocity as a value between 0 and 1 (will be converted to a MIDI velocity between 0 and 127) |
on: |
If specified and false/nil/0 will stop the midi note on message from being sent out. (Ensures all opts are evaluated in this call to |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
# Example 8 | |
|
|
# Example 9 | |
|
|
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_pc program_num (midi)
Sends a MIDI program change message to all connected devices on all channels. Use the port:
and channel:
opts to restrict which MIDI ports and channels are used.
Program number can be passed as a note such as :e3
and decimal values will be rounded down or up to the nearest whole number - so values between 3.5 and 4 will be rounded up to 4 and values between 3.49999… and 3 will be rounded down to 3.
MIDI 1.0 Specification - Channel Voice Messages - Program change
Introduced in v3.0.2
channel: |
Channel(s) to send to |
port: |
MIDI port(s) to send to |
on: |
If specified and false/nil/0 will stop the midi pc message from being sent out. (Ensures all opts are evaluated in this call to |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
midi_pitch_bend delta (float01)
Sends a MIDI pitch bend message to all connected devices on all channels. Use the port:
and channel:
opts to restrict which MIDI ports and channels are used.
Delta value is between 0 and 1 with 0.5 representing no pitch bend, 1 max pitch bend and 0 minimum pitch bend.
Typical MIDI values such as note or cc are represented with 7 bit numbers which translates to the range 0-127. This makes sense for keyboards which have at most 88 keys. However, it translates to a poor resolution when working with pitch bend. Therefore, pitch bend is unlike most MIDI values in that it has a much greater range: 0 - 16383 (by virtue of being represented by 14 bits).
delta_midi:
opt.delta_midi:
opt no pitch bend is the value 8192MIDI 1.0 Specification - Channel Voice Messages - Pitch Bend Change
Introduced in v3.0
channel: |
Channel(s) to send to |
port: |
MIDI port(s) to send to |
delta: |
Pitch bend value as a number between 0 and 1 (will be converted to a value between 0 and 16383). No bend is the central value 0.5 |
delta_midi: |
Pitch bend value as a number between 0 and 16383 inclusively. No bend is central value 8192. |
on: |
If specified and false/nil/0 will stop the midi pitch bend message from being sent out. (Ensures all opts are evaluated in this call to |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
midi_poly_pressure note (midi), value (midi)
Sends a MIDI polyphonic key pressure message to all connected devices on all channels. Use the port:
and channel:
opts to restrict which MIDI ports and channels are used.
Note number and pressure value can be passed as a note such as :e3
and decimal values will be rounded down or up to the nearest whole number - so values between 3.5 and 4 will be rounded up to 4 and values between 3.49999… and 3 will be rounded down to 3.
You may also optionally pass the pressure value as a floating point value between 0 and 1 such as 0.2 or 0.785 (which will be mapped to MIDI values between 0 and 127) using the val_f:
opt.
MIDI 1.0 Specification - Channel Voice Messages - Polyphonic Key Pressure (Aftertouch)
Introduced in v3.0
channel: |
Channel(s) to send to |
port: |
MIDI port(s) to send to |
value: |
Pressure value as a MIDI number. |
val_f: |
Pressure value as a value between 0 and 1 (will be converted to a MIDI value) |
on: |
If specified and false/nil/0 will stop the midi poly pressure message from being sent out. (Ensures all opts are evaluated in this call to |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
midi_raw a (byte), b (byte), c (byte)
Sends the raw MIDI message to all connected MIDI devices. Gives you direct access to the individual bytes of a MIDI message. Typically this should be rarely used - prefer the other midi_
fns where possible.
A raw MIDI message consists of 3 separate bytes - the Status Byte and two Data Bytes. These may be passed as base 10 decimal integers between 0 and 255, in hex form by prefixing 0x
such as 0xb0
which in decimal is 176 or binary form by prefixing 0b
such as 0b01111001
which represents 121 in decimal.
Floats will be rounded up or down to the nearest whole number e.g. 176.1 -> 176, 120.5 -> 121, 0.49 -> 0.
Non-number values will be automatically turned into numbers prior to sending the event if possible (if this conversion does not work an Error will be thrown).
See https://www.midi.org/specifications/item/table-1-summary-of-midi-message for a summary of MIDI messages and their corresponding byte structures.
Introduced in v3.0
port: |
Port(s) to send the raw MIDI message events to |
on: |
If specified and false/nil/0 will stop the raw midi message from being sent out. (Ensures all opts are evaluated in this call to |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
midi_reset value (number)
Sends a MIDI reset all controllers message to all connected devices on all channels. Use the port:
and channel:
opts to restrict which MIDI ports and channels are used.
All controller values are reset to their defaults.
MIDI 1.0 Specification - Channel Mode Messages - Reset All Controllers
Introduced in v3.0
channel: |
Channel to send the midi reset message to |
port: |
MIDI port to send to |
value: |
Value must only be zero (the default) unless otherwise allowed in a specific Recommended Practice |
on: |
If specified and false/nil/0 will stop the midi reset message from being sent out. (Ensures all opts are evaluated in this call to |
# Example 1 | |
|
|
# Example 2 | |
|
|
midi_sound_off
Sends a MIDI sound off message to all connected devices on all channels. Use the port:
and channel:
opts to restrict which MIDI ports and channels are used.
All oscillators will turn off, and their volume envelopes are set to zero as soon as possible.
MIDI 1.0 Specification - Channel Mode Messages - All Sound Off
Introduced in v3.0
channel: |
Channel to send the sound off message to |
port: |
MIDI port to send to |
on: |
If specified and false/nil/0 will stop the midi sound off on message from being sent out. (Ensures all opts are evaluated in this call to |
# Example 1 | |
|
|
# Example 2 | |
|
|
midi_start ()
Sends the MIDI start system message to all connected MIDI devices on all ports. Use the port:
opt to restrict which MIDI ports are used.
Start the current sequence playing. (This message should be followed with calls to midi_clock_tick
or midi_clock_beat
).
MIDI 1.0 Specification - System Real-Time Messages - Start
Introduced in v3.0
# Example 1 | |
|
|
midi_stop ()
Sends the MIDI stop system message to all connected MIDI devices on all ports. Use the port:
opt to restrict which MIDI ports are used.
Stops the current sequence.
MIDI 1.0 Specification - System Real-Time Messages - Start
Introduced in v3.0
port: |
MIDI Port(s) to send the stop message to |
# Example 1 | |
|
|
midi_sysex
Sends the MIDI SysEx message to all connected MIDI devices.
MIDI SysEx messages, unlike all other MIDI messages, are variable in length. They allow MIDI device manufacturers to define device-specific messages, for example loading/saving patches, or programming device features such as illuminated buttons.
Floats will be rounded up or down to the nearest whole number e.g. 176.1 -> 176, 120.5 -> 121, 0.49 -> 0.
Non-number values will be automatically turned into numbers prior to sending the event if possible (if this conversion does not work an Error will be thrown).
Introduced in v3.2
port: |
Port(s) to send the MIDI SysEx message events to |
on: |
If specified and false/nil/0 will stop the midi SysEx message from being sent out. (Ensures all opts are evaluated in this call to |
# Example 1 | |
|
|
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 | |
|
|
osc path (arguments)
Sends an OSC message to the current host and port specified by use_osc
or with_osc
.
OSC (Open Sound Control) is a simple way of passing messages between two separate programs on the same computer or even on different computers via a local network or even the internet. osc
enables you to send well-timed OSC messages from within Sonic Pi. osc
will ensure that the OSC message is sent at the correct time using the same timing system shared with the synthesis functionality via sample
, synth
and friends. osc
even works seamlessly within time_warp
- see examples.
A typical OSC message has two parts: a descriptive path
which looks simalar to a URL (website address), and an optional list of arguments
that are either numbers or strings.
For example, a hypothetical synth program might accept this OSC message:
/set/filter lowpass 80 0.5
where /set/filter
is the path, and lowpass
, 80
, and 0.5
are three
arguments. This can be sent from within Sonic Pi by writing:
osc "/set/filter", "lowpass", 80, 0.5
However, in order to send the OSC message you must first specify where to send it to. This is achieved by specifying both the host (the machine’s internet address) and the port that the remote OSC server is listening on. This is configured using use_osc
or with_osc
. So, if our synth program was running on a machine on the local network with IP address 10.0.1.5
on port 5100
we could send our OSC message to it with the following:
use_osc "10.0.1.5", 5100
osc "/set/filter", "lowpass", 80, 0.5
Note, by default, Sonic Pi listens for OSC messages on port 4560
, so you may send messages to an external machine running Sonic Pi if you know the IP address of that external machine. Any OSC messages received on port 4559
are automatically converted to standard cue events and displayed in the GUI’s cue log. This also means that you can use sync
to wait for the next incoming OSC message with a given path (see example).
Finally, it is also very useful to send OSC messages to aother programs on the same computer. This can be achieved by specifying “localhost” as the hostname and the port as normal (depending on which port the other program is listening on).
See osc_send
for a version which allows you to specify the hostname and port directly (ignoring any values set via use_osc
or with_osc
).
For further information see the OSC spec: http://opensoundcontrol.org/spec-1_0
Introduced in v3.0
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
osc_send hostname (string), port (number), path (osc_path), args (list)
Similar to osc
except ignores any use_osc
settings and sends the OSC message directly to the specified hostname
and port
.
See osc
for more information.
Introduced in v3.0
# Example 1 | |
|
|
# Example 2 | |
|
|
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 a size of 1.
If no arguments are given, will return a lambda function which when called takes an argument which will be a list to be picked from. This is useful for choosing random onset:
vals for samples.
Always returns a list-like thing (either an array or ring)
Introduced in v2.10
skip: |
Number of rands to skip over with each successive pick |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
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.
If duration:
is supplied and sustain:
isn’t, it causes sustain:
to be set so that all four phases add up to the duration.
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 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
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_i_look 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
.
Does not consume a random value from the stream. Therefore, multiple sequential calls to rand_i_look
will all return the same value.
Introduced in v2.11
# Example 1 | |
|
|
# Example 2 | |
|
|
rand_look max (number_or_range)
Given a max number, produces a number between 0
and the supplied max value exclusively. If max is a range produces an int within the range. With no args returns a value between 0
and 1
.
Does not consume a random value from the stream. Therefore, multiple sequential calls to rand_look
will all return the same value.
Introduced in v2.11
# Example 1 | |
|
|
# Example 2 | |
|
|
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 ()
All settings such as the current synth, BPM, random stream and tick values will be reset to the values inherited from the parent thread. Consider using clear
to reset all these values to their defaults.
Introduced in v2.11
# Example 1 | |
|
|
# Example 2 | |
|
|
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 | |
|
|
run_code code (string)
Executes the code passed as a string in a new Run. This works as if the code was in a buffer and Run button was pressed.
Introduced in v2.11
# Example 1 | |
|
|
# Example 2 | |
|
|
run_file filename (path)
Reads the full contents of the file with path
and executes it in a new Run. This works as if the code in the file was in a buffer and Run button was pressed.
Introduced in v2.11
# 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
, .ogg
, .oga
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
.
It is possible to set the start:
and finish:
positions within the sample to play only a sub-section of it. These values can be automatically chosen based on an onset detection algorithm which will essentially isolate each individual drum or synth hit in the sample and let you access each one by an integer index (floats will be rounded to the nearest integer value). See the onset:
docstring and examples for more information.
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."/foo/bar/**"
- Folder strings ending with **
will add all samples contained within all subfolders (searched recursively)."/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.lambda {|s| [s.choose] }
- the ultimate power tool for filters. Allows you to create a custom fn which receives a list of candidates as an arg and which should return a new list of candidates (this may be smaller, larger, re-ordered it’s up to you).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. |
onset: |
Analyse the sample with an onset detection algorithm and automatically set or override the |
on: |
If specified and false/nil/0 will stop the sample from being played. Ensures all opts are evaluated. |
slice: |
Divides the sample duration evenly into |
num_slices: |
Number of slices to divide the sample into when using the |
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. |
path: |
Path of the sample to play. Typically this opt is rarely used instead of the more powerful source/filter system. However it can be useful when working with pre-made opt maps. |
# 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 | |
|
|
# Example 27 | |
|
|
# Example 28 | |
|
|
# Example 29 | |
|
|
# Example 30 | |
|
|
# Example 31 | |
|
|
# Example 32 | |
|
|
# Example 33 | |
|
|
# Example 34 | |
|
|
# Example 35 | |
|
|
# Example 36 | |
|
|
# Example 37 | |
|
|
# Example 38 | |
|
|
# Example 39 | |
|
|
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
, .ogg
, .oga
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
, .ogg
, .oga
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 | |
|
|
scsynth_info ()
Create a map of information about the running audio synthesiser SuperCollider.
Introduced in v2.11
# Example 1 | |
|
|
set time_state_key (default), value (anything)
Store information in the Time State for the current time for either the current or any other thread. If called multiple times without an intervening call to sleep
, sync
, set
or cue
, the last value set will prevail. The value will remain in the Time State until overwritten by another call to set
, or until Sonic Pi quits.
May be used within a time_warp
to set past/future events. Does not affect time.
Introduced in v3.0
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
set_audio_latency! milliseconds (number)
On some systems with certain configurations (such as wireless speakers, and even a typical Windows environment with the default audio drivers) the audio latency can be large. If all the user is doing is generating audio via calls such as play
, synth
and sample
, then this latency essentially adds to the schedule ahead time and for the most part can be ignored. However, if the user is combining audio with external MIDI/OSC triggered events, this latency can result in a noticeable offset. This function allows you to address this offset by moving the audio events forwards and backwards in time.
So, for example, if your audio system has an audio latency of 150ms, you can compensate for this by setting Sonic Pi’s latency to be a negative value: set_audio_latency! -150
.
Introduced in v3.1
# Example 1 | |
|
|
# Example 2 | |
|
|
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_recording_bit_depth! bit_depth (number)
When you hit the record button, Sonic Pi saves all the audio you can hear into a wav file. By default, this file uses a resolution of 16 bits which is the same as CD audio and good enough for most use cases. However, when working with professional equipment, it is common to want to work with even higher quality files such as 24 bits and even 32 bits. This function allows you to switch the default from 16 to one of 8, 16, 24 or 32.
Introduced in v2.11
# 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
. The BPM of the cueing thread can optionally be inherited by 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.
If a block is given, it is assumed to take one arg which will be the controllable synth node and the body of the block is run in an implicit in_thread
. This allows for asynchronous control of the synth without interfering with time. For synchronous control capture the result of synth
as a variable and use that.
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 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
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 | |
|
|
# Example 9 | |
|
|
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
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 | |
|
|
time_warp delta_time (number)
The code within the given block is executed with the specified delta time shift specified in beats. For example, if the delta value is 0.1 then all code within the block is executed with a 0.1 beat delay. Negative values are allowed which means you can move a block of code backwards in time. For example a delta value of -0.1 will execute the code in the block 0.1 beats ahead of time. The time before the block started is restored after the execution of the block.
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 that the code within the block is executed synchronously with the code before and after, so all thread locals will be modified inline - as is the case for with_fx
. However, as time is always restored to the value before time_warp
started, you can use it to schedule events for the future in a similar fashion to a thread (via at
or in_thread
) without having to use an entirely fresh and distinct set of thread locals - see examples.
Also, note that you cannot travel backwards in time beyond the current_sched_ahead_time
.
If the time_warp
block is within a density
block, the delta time is not affected (although all the other times such as sleep and phase durations will be affected) - see example.
time_warp
is ahead-of-time scheduling within the current thread. See at
for just-in-time scheduling using multiple isolated threads.
Introduced in v2.11
# 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 | |
|
|
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 transpose 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_midi_defaults
Specify new default values to be used by all subsequent calls to midi_*
fns. Merges the specified values with any previous defaults, rather than replacing them
Introduced in v3.0
# Example 1 | |
|
|
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_midi_defaults
Specify new default values to be used by all subsequent calls to midi_*
fns. Will remove and override any previous defaults.
Introduced in v3.0
# Example 1 | |
|
|
use_midi_logging true_or_false (boolean)
Enable or disable log messages created on MIDI functions. This does not disable the MIDI functions themselves, it just stops them from being printed to the log
Introduced in v3.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_osc hostname (string), port (number)
Sets the destination host and port that osc
will send messages to. If no port number is specified - will default to port 4560 (Sonic Pi’s default OSC listening port).
OSC (Open Sound Control) is a simple way of passing messages between two separate programs on the same computer or even on different computers via a local network or even the internet. use_osc
allows you to specify which computer (hostname
) and program (port
) to send messages to.
It is possible to send messages to the same computer by using the host name "localhost"
This is a thread-local setting - therefore each thread (or live loop) can have their own separate use_osc
values.
Note that calls to osc_send
will ignore these values.
Introduced in v3.0
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
use_osc_logging true_or_false (boolean)
Enable or disable log messages created on OSC functions. This does not disable the OSC functions themselves, it just stops them from being printed to the log
Introduced in v3.0
# 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_random_stream noise_type (symbol)
Sets the random number source to be one of :white, :pink, :light_pink, :dark_pink or :perlin. :white is totally random - between 0 and 1, you can expect an even spread of values around 0.1, 0.2, 0.3 etc. This means that jumping around within the range (including large jumps) is expected. :pink is more likely to produce values in the middle of the range and less likely to produce values at the extremes. Between 0 and 1 you expect to see a concentration of values around 0.5. This can make random melodies a little bit more smooth. :perlin is a special kind of noise which produces gradients, a bit like a mountain landscape. Large jumps are much less likely and you will tend to see lots of smooth motion going either up or down :light_pink is halfway between white noise and pink noise - more random and jumpy :dark_pink is halfway between pink noise and brown noise - less jumpy with smoother slopes You can see the ‘buckets’ that the numbers between 0 and 1 fall into with the following code:
rand_type :white
puts 10000.times.collect { rand.round(1) }.tally.sort
rand_type :pink
puts 10000.times.collect { rand.round(1) }.tally.sort
rand_type :perlin
puts 10000.times.collect { rand.round(1) }.tally.sort
Introduced in v3.2.3
# Example 1 | |
|
|
use_real_time ()
Set sched ahead time to 0 for the current thread. Shorthand for use_sched_ahead_time 0
.
See use_sched_ahead_time
for a version of this function which allows you to set the schedule ahead time to any arbitrary value. Note, use_real_time
will override any value set with set_sched_ahead_time!
for the current thread.
Introduced in v3.0
# Example 1 | |
|
|
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_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.
See set_sched_ahead_time!
for a global version of this function. Note, use_sched_ahead_time
will override any value set with set_sched_ahead_time!
for the current thread.
See use_real_time
for a simple way of setting the schedule ahead time to 0.
Introduced in v3.0
# Example 1 | |
|
|
# Example 2 | |
|
|
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 transpose 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_midi_defaults
Specify opt values to be used by any following call to the midi_*
fns within the specified do
/end
block. Merges the specified values with any previous midi defaults, rather than replacing them. After the do
/end
block has completed, previous defaults (if any) are restored.
Introduced in v3.0
# Example 1 | |
|
|
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_midi_defaults
Specify new default values to be used by all calls to midi_*
fns within the do
/end
block. After the do
/end
block has completed the previous MIDI defaults (if any) are restored.
Introduced in v3.0
# Example 1 | |
|
|
with_midi_logging true_or_false (boolean)
Similar to use_midi_logging except only applies to code within supplied do
/end
block. Previous MIDI log value is restored after block.
Introduced in v3.0
# Example 1 | |
|
|
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_osc hostname (string), port (number)
Sets the destination host and port that osc
will send messages to for the given do/end block.
Introduced in v3.0
# Example 1 | |
|
|
with_osc_logging true_or_false (boolean)
Similar to use_osc_logging except only applies to code within supplied do
/end
block. Previous OSC log value is restored after block.
Introduced in v3.0
# 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_random_stream noise_type (symbol)
Resets the random number generator to the specified noise type 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 v3.2.3
# Example 1 | |
|
|
with_real_time ()
Sets sched ahead time to 0 within the block for the current thread. Shorthand for with_sched_ahead_time 0
.
See with_sched_ahead_time
for a version of this function which allows you to set the schedule ahead time to any arbitrary value. Note, with_real_time
will override any value set with set_sched_ahead_time!
for the current thread.
Introduced in v3.0
# Example 1 | |
|
|
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_sched_ahead_time time (number)
Specify how many seconds ahead of time the synths should be triggered for the block. See use_sched_ahead_time
for further information.
See set_sched_ahead_time!
for a global version of this function. Note, with_sched_ahead_time
will override any value set with set_sched_ahead_time!
for the given block within the current thread.
See with_real_time
for a simple way of setting the schedule ahead time to 0.
Introduced in v3.0
# Example 1 | |
|
|
with_swing shift (beats), pulse (number), tick (symbol)
Runs block within a time_warp
except for once every pulse
consecutive runs (defaulting to 4). When used for rhythmical purposes this results in one in every pulse
calls of the block being ‘on beat’ and the rest shifted forward or backwards in time by shift
beats.
Introduced in v3.0
shift: |
How much time to delay/forward the block. Greater values produce more emphasised swing. Defaults to 0.1 beats. |
pulse: |
How often to apply the swing. Defaults to 4. |
tick: |
A key for the tick with which to count pulses. Override this if you have more than one |
offset: |
Count offset - before modding the count with the pulse size - integer offset to add to the result of calling |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
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 | |
|
|