all_sample_names
Return a list of all the sample names available
Introduced in v2.0
assert arg (anything)
Raises an exception if the argument is either nil or false.
Introduced in v2.8
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
assert_equal arg1 (anything), arg2 (anything)
Raises an exception if both arguments aren’t equal.
Introduced in v2.8
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
at times (list), params (list)
Given a list of times, run the block once after waiting each given time. If passed an optional params list, will pass each param individually to each block call. If size of params list is smaller than the times list, the param values will act as rings (rotate through). If the block is given 1 arg, the times are fed through. If the block is given 2 args, both the times and the params are fed through. A third block arg will receive the index of the time.
Introduced in v2.1
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
bools list (array)
Create a new ring of booleans values from 1s and 0s, which can be easier to write and manipulate in a live setting.
Introduced in v2.2
# Example 1 | |
|
|
# Example 2 | |
|
|
bt seconds (number)
Beat time representation. Scales the time to the current BPM. Useful for adding bpm scaling
Introduced in v2.8
# Example 1 | |
|
|
choose list (array)
Choose an element at random from a list (array).
Introduced in v2.0
# Example 1 | |
|
|
chord tonic (symbol), name (symbol)
Creates an immutable ring of Midi note numbers when given a tonic note and a chord type
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 | |
|
|
chord_degree degree (symbol_or_number), tonic (symbol), scale (symbol), number_of_notes (number)
In music we build chords from scales. For example, a C major chord is made by taking the 1st, 3rd and 5th notes of the C major scale (C, E and G). If you do this on a piano you might notice that you play one, skip one, play one, skip one etc. If we use the same spacing and start from the second note in C major (which is a D), we get a D minor chord which is the 2nd, 4th and 6th notes in C major (D, F and A). We can move this pattern all the way up or down the scale to get different types of chords. chord_degree
is a helper method that returns a ring of midi note numbers when given a degree (starting point in a scale) which is a symbol :i
, :ii
, :iii
, :iv
, :v
, :vi
, :vii
or a number 1
-7
. The second argument is the tonic note of the scale, the third argument is the scale type and finally the fourth argument is number of notes to stack up in the chord. If we choose 4 notes from degree :i
of the C major scale, we take the 1st, 3rd, 5th and 7th notes of the scale to get a C major 7 chord.
Introduced in v2.1
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
chord_names
Returns a ring containing all chord names known to Sonic Pi
Introduced in v2.6
# Example 1 | |
|
|
comment
Does not evaluate any of the code within the block. However, any optional args passed before the block will be evaluated although they will be ignored. See uncomment
for switching commenting off without having to remove the comment form.
Introduced in v2.0
# Example 1 | |
|
|
control node (synth_node)
Control a running synth node by passing new parameters to it. A synth node represents a running synth and can be obtained by assigning the return value of a call to play or sample or by specifying a parameter to the do/end block of an FX. You may modify any of the parameters you can set when triggering the synth, sample or FX. See documentation for opt details. If the synth to control is a chord, then control will change all the notes of that chord group at once to a new target set of notes - see example.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
# Example 8 | |
|
|
cue cue_id (symbol)
Send a heartbeat synchronisation message containing the (virtual) timestamp of the current thread. Useful for syncing up external threads via the sync
fn. Any opts which are passed are given to the thread which syncs on the cue_id
as a map. The values of the opts must be immutable. Currently only numbers, symbols and booleans are supported.
Introduced in v2.0
your_key: |
Your value |
another_key: |
Another value |
key: |
All these opts are passed through to the thread which syncs |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
current_arg_checks
Returns the current arg checking setting (true
or false
).
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
.
Introduced in v2.6
# Example 1 | |
|
|
current_bpm
Returns the current tempo as a bpm value.
Introduced in v2.0
# Example 1 | |
|
|
current_debug
Returns the current debug setting (true
or false
).
Introduced in v2.0
# Example 1 | |
|
|
current_sample_defaults
Returns the current sample defaults. This is a map of synth arg names to either values or functions.
Introduced in v2.5
# Example 1 | |
|
|
current_sample_pack
Returns the current sample pack.
Introduced in v2.0
# Example 1 | |
|
|
current_sample_pack_aliases
Returns a map containing the current sample pack aliases.
Introduced in v2.0
# Example 1 | |
|
|
current_sched_ahead_time
Returns the current schedule ahead time.
Introduced in v2.0
# Example 1 | |
|
|
current_synth
Returns the current synth name.
Introduced in v2.0
# Example 1 | |
|
|
current_synth_defaults
Returns the current synth defaults. This is a map of synth arg names to either values or functions.
Introduced in v2.0
# Example 1 | |
|
|
current_transpose
Returns the current transpose value.
Introduced in v2.0
# Example 1 | |
|
|
current_volume
Returns the current volume.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
dec n (number)
Decrement a number by 1
. Equivalent to n - 1
Introduced in v2.1
# Example 1 | |
|
|
# Example 2 | |
|
|
define name (symbol)
Allows you to group a bunch of code and give it your own name for future re-use. Functions are very useful for structuring your code. They are also the gateway into live coding as you may redefine a function whilst a thread is calling it, and the next time the thread calls your function, it will use the latest definition.
Introduced in v2.0
# Example 1 | |
|
|
defonce name (symbol)
Allows you to assign the result of some code to a name, with the property that the code will only execute once - therefore stopping re-definitions. This is useful for defining values that you use in your compositions but you don’t want to reset every time you press run. You may force the block to execute again regardless of whether or not it has executed once already by using the override option (see examples).
Introduced in v2.0
override: |
If set to true, re-definitions are allowed and this acts like define |
# Example 1 | |
|
|
# Example 2 | |
|
|
degree degree (symbol_or_number), tonic (symbol), scale (symbol)
For a given scale and tonic it takes a symbol :i
, :ii
, :iii
, :iv
,:v
, :vi
, :vii
or a number 1
-7
and resolves it to a midi note.
Introduced in v2.1
# Example 1 | |
|
|
density d (density)
Runs the block d
times with the bpm for the block also multiplied by d
. Great for repeating sections a number of times faster yet keeping within a fixed time. If d
is less than 1, then time will be stretched accordingly and the block will take longer to complete.
Introduced in v2.3
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
dice num_sides (number)
Throws a dice with the specified num_sides (defaults to 6
) and returns the score as a number between 1
and num_sides
.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
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 | |
|
|
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. Finally, 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.
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. |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
inc n (number)
Increment a number by 1
. Equivalent to n + 1
Introduced in v2.1
# Example 1 | |
|
|
# Example 2 | |
|
|
inspect output (anything)
Displays the information you specify as an inspected string inside the output pane. This can be a number, symbol, or a string itself.
Introduced in v2.8
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
invert_chord 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 | |
|
|
kill node (synth_node)
Kill a running synth sound or sample. In order to kill a sound, you need to have stored a reference to it in a variable.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
knit value (anything), count (number)
Knits a series of value, count pairs to create a ring buffer where each value is repeated count times.
Introduced in v2.2
# Example 1 | |
|
|
# Example 2 | |
|
|
line start (number), finish (number)
Create a ring buffer representing a straight line between start and finish of num_slices elements. Num slices defaults to 8
. Indexes wrap around positively and negatively. Similar to range
.
Introduced in v2.5
steps: |
number of slices or segments along the line |
inclusive: |
boolean value representing whether or not to include finish value in line |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
live_loop name (symbol)
Run the block in a new thread with the given name, and loop it forever. Also sends a cue
with the same name each time the block runs. If the block is given a parameter, this is given the result of the last run of the loop (with initial value either being 0
or an init arg).
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. |
seed: |
override initial random generator seed before starting loop. |
# Example 1 | |
|
|
# Example 2 | |
|
|
load_sample path (string)
Given a path to a .wav
, .wave
, .aif
or .aiff
file, this loads the file and makes it available as a sample. See load_samples
for loading multiple samples in one go.
Introduced in v2.0
# Example 1 | |
|
|
load_samples paths (list)
Given an array of paths to .wav
, .wave
, .aif
or .aiff
files, loads them all into memory so that they may be played with via sample with no delay. See load_sample
.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
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.
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))}
).store;
)
The location of the binary synthdef file written to disk by .store
is platform dependent. In SuperCollider, run Platform.userAppSupportDir
to find out where this directory exists on your machine and then navigate to the synthdefs
folder. For example, on my Mac this dir is:
/Users/sam/Library/Application Support/SuperCollider/synthdefs
Introduced in v2.0
# Example 1 | |
|
|
look
Read and return value of default tick. If a key
is specified, read the value of that specific tick. Ticks are in_thread
and live_loop
local, so the tick read will be the tick of the current thread calling look
.
Introduced in v2.6
offset: |
Offset to add to index returned. Useful when calling look on lists, rings and vectors to offset the returned value |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
mc_block_id name (symbol_or_number)
Given a block name or id will return a number representing the id of the block or throw an exception if the name or id isn’t valid
Introduced in v2.5
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
mc_block_ids
Returns a list of all the valid block ids as numbers. Note not all numbers are valid block ids. For example, 19 is not a valid block id.
Introduced in v2.5
# Example 1 | |
|
|
mc_block_name id (number_or_symbol)
Given a block id or a block name will return a symbol representing the block name or throw an exception if the id or name isn’t valid.
Introduced in v2.5
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
mc_block_names
Returns a list of all the valid block names as symbols
Introduced in v2.5
# Example 1 | |
|
|
mc_camera_fixed
Set the camera mode to fixed.
Introduced in v2.5
# Example 1 | |
|
|
mc_camera_normal
Set the camera mode to normal.
Introduced in v2.5
# Example 1 | |
|
|
mc_camera_set_location
Move the camera to a new location.
Introduced in v2.5
# Example 1 | |
|
|
mc_camera_third_person
Set the camera mode to third person
Introduced in v2.5
# Example 1 | |
|
|
mc_chat_post
See mc_message
Introduced in v2.5
mc_checkpoint_restore
Restore the world to the last snapshot taken with mc_checkpoint_save
.
Introduced in v2.5
# Example 1 | |
|
|
mc_checkpoint_save
Take a snapshot of the world and save it. Restore back with mc_checkpoint_restore
Introduced in v2.5
# Example 1 | |
|
|
mc_get_block x (number), y (number), z (number)
Returns the type of the block at the coords x
, y
, z
as a symbol.
Introduced in v2.5
# Example 1 | |
|
|
mc_get_height
See mc_ground_height
Introduced in v2.5
mc_get_pos
See mc_location
Introduced in v2.5
mc_get_tile
Returns the coordinates of the nearest block that the player is next to. This is more course grained than mc_location
as it only returns whole number coordinates.
Introduced in v2.5
# Example 1 | |
|
|
mc_ground_height x (number), z (number)
Returns the height of the ground at the specified x
and z
coords.
Introduced in v2.5
# Example 1 | |
|
|
mc_location
Returns a list of floats [x, y, z]
coords of the current location for Steve. The coordinates are finer grained than raw block coordinates but may be used anywhere you might use block coords.
Introduced in v2.5
# Example 1 | |
|
|
# Example 2 | |
|
|
mc_message msg (string)
Post contents of msg
on the Minecraft chat display. You may pass multiple arguments and all will be joined to form a single message (with spaces).
Introduced in v2.5
# Example 1 | |
|
|
mc_set_area block_name (symbol_or_number), x (number), y (number), z (number), x2 (number), y2 (number), z2 (number)
Set an area/box of blocks of type block_name
defined by two distinct sets of coordinates.
Introduced in v2.5
mc_set_block x (number), y (number), z (number), block_name (symbol_or_number)
Change the block type of the block at coords x
, y
, z
to block_type
. The block type may be specified either as a symbol such as :air
or a number. See mc_block_ids
and mc_block_types
for lists of valid symbols and numbers.
Introduced in v2.5
# Example 1 | |
|
|
mc_set_pos
See mc_teleport
Introduced in v2.5
mc_set_tile x (number), y (number), z (number)
Introduced in v2.5
# Example 1 | |
|
|
mc_surface_teleport x (number), z (number)
Teleports you to the specified x and z coordinates with the y automatically set to place you on the surface of the world. For example, if the x and z coords target a mountain, you’ll be placed on top of the mountain, not in the air or under the ground. See mc_ground_height for discovering the height of the ground at a given x, z point.
Introduced in v2.5
# Example 1 | |
|
|
mc_teleport x (number), y (number), z (number)
Magically teleport the player to the location specified by the x
, y
, z
coordinates. Use this for automatically moving the player either small or large distances around the world.
Introduced in v2.5
# Example 1 | |
|
|
midi_notes list (array)
Create a new immutable ring buffer of notes from args. Indexes wrap around positively and negatively. Final ring consists only of MIDI numbers and nil.
Introduced in v2.7
# Example 1 | |
|
|
# Example 2 | |
|
|
midi_to_hz note (symbol_or_number)
Convert a midi note to hz
Introduced in v2.0
# Example 1 | |
|
|
ndefine name (symbol)
Does nothing. Use to stop a define from actually defining. Simpler than wrapping whole define in a comment block or commenting each individual line out.
Introduced in v2.1
note note (symbol_or_number)
Takes a midi note, a symbol (e.g. :C
) or a string (e.g. "C"
) and resolves it to a midi note. You can also pass an optional octave:
parameter to get the midi note for a given octave. Please note - octave:
param overrides any octave specified in a symbol i.e. :c3
. If the note is nil
, :r
or :rest
, then nil
is returned (nil
represents a rest)
Introduced in v2.0
octave: |
The octave of the note. Overrides any octave declaration in the note symbol such as :c2. Default is 4 |
# Example 1 | |
|
|
# Example 2 | |
|
|
note_info note (symbol_or_number)
Returns an instance of SonicPi::Note
. Please note - octave:
param overrides any octave specified in a symbol i.e. :c3
Introduced in v2.0
octave: |
The octave of the note. Overrides any octave declaration in the note symbol such as :c2. Default is 4 |
# Example 1 | |
|
|
note_range low_note (note), high_note (note)
Produces a ring of all the notes between a low note and a high note. By default this is chromatic (all the notes) but can be filtered with a :pitches argument. This opens the door to arpeggiator style sequences and other useful patterns. If you try to specify only pitches which aren’t in the range it will raise an error - you have been warned!
Introduced in v2.6
pitches: |
An array of notes (symbols or ints) to filter on. Octave information is ignored. |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
octs start (note), num_octaves (pos_int)
Create a ring of successive octaves starting at start
for num_octaves
.
Introduced in v2.8
# Example 1 | |
|
|
# Example 2 | |
|
|
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 | |
|
|
pitch_to_ratio pitch (midi_number)
Convert a midi note to a ratio which when applied to a frequency will scale the frequency by the number of semitones. Useful for changing the pitch of a sample by using it as a way of generating the rate.
Introduced in v2.5
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
play note (symbol_or_number)
Play note with current synth. Accepts a set of standard options which include control of an amplitude envelope with attack:
, decay:
, sustain:
and release:
phases. These phases are triggered in order, so the duration of the sound is attack + decay + sustain + release times. The duration of the sound does not affect any other notes. Code continues executing whilst the sound is playing through its envelope phases.
Accepts optional args for modification of the synth being played. See each synth’s documentation for synth-specific opts. See use_synth
and with_synth
for changing the current synth.
If note is nil
, :r
or :rest
, play is ignored and treated as a rest.
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 |
on: |
If specified and false/nil/0 will stop the synth from being played. Ensures all opts are evaluated. |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
play_chord notes (list)
Play a list of notes at the same time.
Accepts optional args for modification of the synth being played. See each synth’s documentation for synth-specific opts. See use_synth
and with_synth
for changing the current synth.
Introduced in v2.0
amp: |
The amplitude of the note |
amp_slide: |
The duration in beats for amplitude changes to take place |
pan: |
The stereo position of the sound. -1 is left, 0 is in the middle and 1 is on the right. You may use a value in between -1 and 1 such as 0.25 |
pan_slide: |
The duration in beats for the pan value to change |
attack: |
Amount of time (in beats) for sound to reach full amplitude (attack_level). A short attack (i.e. 0.01) makes the initial part of the sound very percussive like a sharp tap. A longer attack (i.e 1) fades the sound in gently. |
decay: |
Amount of time (in beats) for the sound to move from full amplitude (attack_level) to the sustain amplitude (sustain_level). |
sustain: |
Amount of time (in beats) for sound to remain at sustain level amplitude. Longer sustain values result in longer sounds. Full length of sound is attack + decay + sustain + release. |
release: |
Amount of time (in beats) for sound to move from sustain level amplitude to silent. A short release (i.e. 0.01) makes the final part of the sound very percussive (potentially resulting in a click). A longer release (i.e 1) fades the sound out gently. |
attack_level: |
Amplitude level reached after attack phase and immediately before decay phase |
decay_level: |
Amplitude level reached after decay phase and immediately before sustain phase. Defaults to sustain_level unless explicitly set |
sustain_level: |
Amplitude level reached after decay phase and immediately before release phase. |
env_curve: |
Select the shape of the curve between levels in the envelope. 1=linear, 2=exponential, 3=sine, 4=welch, 6=squared, 7=cubed |
slide: |
Default slide time in beats for all slide opts. Individually specified slide opts will override this value |
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 |
on: |
If specified and false/nil/0 will stop the synth from being played. Ensures all opts are evaluated. |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
print output (anything)
Displays the information you specify as a string inside the output pane. This can be a number, symbol, or a string itself. Useful for debugging. Synonym for puts
.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
puts output (anything)
Displays the information you specify as a string inside the output pane. This can be a number, symbol, or a string itself. Useful for debugging. Synonym for print
.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
quantise n (number), step (positive_number)
Round value to the nearest multiple of step resolution.
Introduced in v2.1
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
ramp list (array)
Create a new immutable ramp vector from args. Indexes always return first or last value if out of bounds.
Introduced in v2.6
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
rand max (number_or_range)
Given a max number, produces a float between 0
and the supplied max value. If max is a range, produces a float within the range. With no args returns a random value between 0
and 1
.
Introduced in v2.0
# Example 1 | |
|
|
rand_back amount (number)
Roll the random generator back essentially ‘undoing’ the last call to rand
. You may specify an amount to roll back allowing you to skip back n calls to rand
.
Introduced in v2.7
# Example 1 | |
|
|
# Example 2 | |
|
|
rand_i max (number_or_range)
Given a max number, produces a whole number between 0
and the supplied max value exclusively. If max is a range produces an int within the range. With no args returns either 0
or 1
Introduced in v2.0
# Example 1 | |
|
|
rand_reset ()
Resets the random stream to the last specified seed. See use_random_seed
for changing the seed.
Introduced in v2.7
# Example 1 | |
|
|
rand_skip amount (number)
Jump the random generator forward essentially skipping the next call to rand
. You may specify an amount to jump allowing you to skip n calls to rand
.
Introduced in v2.7
# Example 1 | |
|
|
# Example 2 | |
|
|
range start (number), finish (number), step_size (number)
Create a new ring buffer from the range arguments (start, finish and step size). Step size defaults to 1
. Indexes wrap around positively and negatively
Introduced in v2.2
step: |
Size of increment between steps; step size. |
inclusive: |
If set to true, range is inclusive of finish value |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
ratio_to_pitch ratio (number)
Convert a frequency ratio to a midi note which when added to a note will transpose the note to match the frequency ratio.
Introduced in v2.7
# Example 1 | |
|
|
# Example 2 | |
|
|
rdist width (number), centre (number)
Returns a random number within the range with width around centre. If optional arg step:
is used, the result is quantised by step.
Introduced in v2.3
step: |
Step size of value to quantise to. |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
rest? note_or_args (number_symbol_or_map)
Given a note or an args map, returns true if it represents a rest and false if otherwise
Introduced in v2.1
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
# Example 8 | |
|
|
ring list (array)
Create a new immutable ring buffer from args. Indexes wrap around positively and negatively
Introduced in v2.2
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
rrand min (number), max (number)
Given two numbers, this produces a float between the supplied min and max values exclusively. Both min and max need to be supplied. For random integers, see rrand_i
. If optional arg step:
is used, the result is quantised by step.
Introduced in v2.0
step: |
Step size of value to quantise to. |
# Example 1 | |
|
|
# Example 2 | |
|
|
rrand_i min (number), max (number)
Given two numbers, this produces a whole number between the min and max you supplied inclusively. Both min and max need to be supplied. For random floats, see rrand
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
rt seconds (number)
Real time representation. Returns the amount of beats for the value in real-time seconds. Useful for bypassing any bpm scaling
Introduced in v2.0
# Example 1 | |
|
|
sample name_or_path (symbol_or_string)
This is the main method for playing back recorded sound files (samples). Sonic Pi comes with lots of great samples included (see the section under help) but you can also load and play .wav
, .wave
, .aif
or .aiff
files from anywhere on your computer too. 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 two separate envelopes - one for amplitude and one for the cutoff value for a resonant low 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.
Check out the use_sample_pack
and use_sample_pack_as
fns for details on making it easy to work with a whole folder of your own sample files. Note, that on the first trigger of a sample, Sonic Pi has to load the sample which takes some time and may cause timing issues. To preload the samples you wish to work with consider using load_sample
or load_samples
.
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 pitch: opt. Note, it’s very likely you’ll need to experiment with 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 |
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. |
cutoff: |
Cutoff value of the built-in resonant low pass filter (rlpf) in MIDI notes. Unless specified, the rlpf is not added to the signal chain. |
cutoff_attack_level: |
The peak cutoff (value of cutoff at peak of attack) as a MIDI note. Default value is 130. |
cutoff_decay_level: |
The level of cutoff after the decay phase as a MIDI note. Default value is |
cutoff_sustain_level: |
The sustain cutoff (value of cutoff at sustain time) as a MIDI note. Default value is |
cutoff_attack: |
Attack time for 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. |
cutoff_decay: |
Decay time for 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. |
cutoff_sustain: |
Amount of time for cutoff value to remain at sustain level in beats. When -1 (the default) will auto-stretch. |
cutoff_release: |
Amount of time (in beats) for sound to move from cutoff sustain value to cutoff min value. Default value is set to match amp envelope’s release value. |
cutoff_env_curve: |
Select the shape of the curve between levels in the cutoff envelope. 1=linear, 2=exponential, 3=sine, 4=welch, 6=squared, 7=cubed |
res: |
Cutoff-specific opt. Only honoured if cutoff: is specified. Filter resonance as a value between 0 and 1. Large amounts of resonance (a res: near 1) can create a whistling sound around the cutoff frequency. Smaller values produce less resonance. |
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 ie 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: opt is used. Pitch shift works by chopping the input into tiny slices, then playing these slices at a higher or lower rate. If we make the slices small enough and overlap them, it sounds like the original sound with the pitch changed. The window_size is the length of the slices and is measured in seconds. It needs to be around 0.2 (200ms) or greater for pitched sounds like guitar or bass, and needs to be around 0.02 (20ms) or lower for percussive sounds like drum loops. You can experiment with this to get the best sound for your input. |
pitch_dis: |
Pitch shift-specific opt - only honoured if the pitch: opt is used. Pitch dispersion - how much random variation in pitch to add. Using a low value like 0.001 can help to “soften up” the metallic sounds, especially on drum loops. To be really technical, pitch_dispersion is the maximum random deviation of the pitch from the pitch ratio (which is set by the pitch param) |
time_dis: |
Pitch shift-specific opt - only honoured if the pitch: opt is used. Time dispersion - how much random delay before playing each grain (measured in seconds). Again, low values here like 0.001 can help to soften up metallic sounds introduced by the effect. Large values are also fun as they can make soundscapes and textures from the input, although you will most likely lose the rhythm of the original. NB - This won’t have an effect if it’s larger than window_size. |
slide: |
Default slide time in beats for all slide opts. Individually specified slide opts will override this value |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
# Example 8 | |
|
|
# Example 9 | |
|
|
# Example 10 | |
|
|
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
or .aiff
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.
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_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
or .aiff
file, returns true
if the sample has already been loaded.
Introduced in v2.2
# Example 1 | |
|
|
sample_names group (symbol)
Return a list of sample names for the specified group
Introduced in v2.0
scale tonic (symbol), name (symbol)
Creates a ring of MIDI note numbers when given a tonic note and a scale type. Also takes an optional num_octaves:
parameter (octave 1
is the default)
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 | |
|
|
scale_names
Returns a ring containing all scale names known to Sonic Pi
Introduced in v2.6
# 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.
Introduced in v2.7
pre_amp: |
Controls the amplitude of the signal prior to the FX stage of the mixer (prior to lpf/hpf stages). Has slide opts. Default 1. |
amp: |
Controls the amplitude of the signal after the FX stage. Has slide opts. Default 1. |
hpf: |
Global hpf FX. Has slide opts. Default 0. |
lpf: |
Global lpf FX. Has slide opts. Default 135.5. |
hpf_bypass: |
Bypass the global hpf. 0=no bypass, 1=bypass. Default 0. |
lpf_bypass: |
Bypass the global lpf. 0=no bypass, 1=bypass. Default 0. |
limiter_bypass: |
Bypass the final limiter. 0=no bypass, 1=bypass. Default 0. |
leak_dc_bypass: |
Bypass the final DC leak correction FX. 0=no bypass, 1=bypass. Default 0. |
# Example 1 | |
|
|
set_sched_ahead_time! time (number)
Specify how many seconds ahead of time the synths should be triggered. This represents the amount of time between pressing ‘Run’ and hearing audio. A larger time gives the system more room to work with and can reduce performance issues in playing fast sections on slower platforms. However, a larger time also increases latency between modifying code and hearing the result whilst live coding.
Introduced in v2.0
# Example 1 | |
|
|
set_volume! vol (number)
Set the main system volume to vol
. Accepts a value between 0
and 5
inclusive. Vols greater or smaller than the allowed values are trimmed to keep them within range. Default is 1
.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
shuffle list (array)
Returns a new list with the same elements as the original but with their order shuffled. Also works for strings
Introduced in v2.1
# Example 1 | |
|
|
# Example 2 | |
|
|
sleep beats (number)
Wait for a number of beats before triggering the next command. Beats are converted to seconds by scaling to the current bpm setting.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
spark
Given a list of numeric values, this method turns them into a string of bar heights and prints them out. Useful for quickly graphing the shape of an array.
Introduced in v2.5
# Example 1 | |
|
|
# Example 2 | |
|
|
spark_graph
Given a list of numeric values, this method turns them into a string of bar heights. Useful for quickly graphing the shape of an array. Remember to use puts so you can see the output. See spark
for a simple way of printing a spark graph.
Introduced in v2.5
# Example 1 | |
|
|
# Example 2 | |
|
|
spread num_accents (number), size (number)
Creates a new ring of boolean values which space a given number of accents as evenly as possible throughout a bar. This is an implementation of the process described in ‘The Euclidean Algorithm Generates Traditional Musical Rhythms’ (Toussaint 2005).
Introduced in v2.4
rotate: |
rotate to the next strong beat allowing for easy permutations of the original rhythmic grouping (see example) |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
status
This returns a Hash of information about the synthesis environment. Mostly used for debugging purposes.
Introduced in v2.0
# Example 1 | |
|
|
stop
Stops the current thread or if not in a thread, stops the current run. Does not stop any running synths triggered previously in the run/thread or kill any existing sub-threads.
Introduced in v2.5
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
stretch list (anything), count (number)
Stretches a list of values each value repeated count times. Always returns a ring regardless of the type of the list that is stretched. To preserve type, consider using .stretch
i.e. (ramp 1, 2, 3).stretch(2) #=> (ramp 1, 1, 2, 2, 3, 3)
Introduced in v2.6
# Example 1 | |
|
|
# Example 2 | |
|
|
sync cue_id (symbol)
Pause/block the current thread until a cue
heartbeat with a matching cue_id
is received. When a matching cue
message is received, unblock the current thread, and continue execution with the virtual time set to match the thread that sent the cue
heartbeat. The current thread is therefore synced to the cue
thread. If multiple cue ids are passed as arguments, it will sync
on the first matching cue_id
. By default the BPM of the cueing thread is inherited. This can be disabled using the bpm_sync: opt.
Introduced in v2.0
bpm_sync: |
Inherit the BPM of the cueing thread. Default is false |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
synth synth_name (symbol)
Trigger specified synth with given arguments. Bypasses current synth value, yet still honours synth defaults.
Introduced in v2.0
slide: |
Default slide time in beats for all slide opts. Individually specified slide opts will override this value |
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 | |
|
|
tick key (symbol)
Increment the default tick by 1 and return value. Successive calls to tick
will continue to increment the default tick. If a key
is specified, increment that specific tick. If an increment value
is specified, increment key by that value rather than 1. Ticks are in_thread
and live_loop
local, so incrementing a tick only affects the current thread’s version of that tick. See tick_reset
and tick_set
for directly manipulating the tick vals.
Introduced in v2.6
step: |
The amount to tick up by. Default is 1. |
offset: |
Offset to add to index returned. Useful when calling tick on lists, rings and vectors to offset the returned value. Default is 0. |
# Example 1 | |
|
|
# Example 2 | |
|
|
# Example 3 | |
|
|
# Example 4 | |
|
|
# Example 5 | |
|
|
# Example 6 | |
|
|
# Example 7 | |
|
|
# Example 8 | |
|
|
tick_reset
Reset default tick to 0. If a key
is referenced, set that tick to 0 instead. Same as calling tick_set(0)
Introduced in v2.6
# Example 1 | |
|
|
# Example 2 | |
|
|
tick_reset_all value (number)
Reset all ticks - default and keyed
Introduced in v2.6
# Example 1 | |
|
|
tick_set value (number)
Set the default tick to the specified value
. If a key
is referenced, set that tick to value
instead. Next call to look
will return value
.
Introduced in v2.6
# Example 1 | |
|
|
# Example 2 | |
|
|
uncomment
Evaluates all of the code within the block. Use to reverse the effect of the comment without having to explicitly remove it.
Introduced in v2.0
# Example 1 | |
|
|
use_arg_bpm_scaling bool (boolean)
Turn synth argument bpm scaling on or off for the current thread. This is on by default. Note, using rt
for args will result in incorrect times when used after turning arg bpm scaling off.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
use_arg_checks true_or_false (boolean)
When triggering synths, each argument is checked to see if it is sensible. When argument checking is enabled and an argument isn’t sensible, you’ll see an error in the debug pane. This setting allows you to explicitly enable and disable the checking mechanism. See with_arg_checks for enabling/disabling argument checking only for a specific do
/end
block.
Introduced in v2.0
# Example 1 | |
|
|
use_bpm bpm (number)
Sets the tempo in bpm (beats per minute) for everything afterwards. Affects all subsequent calls to sleep
and all temporal synth arguments which will be scaled to match the new bpm. If you wish to bypass scaling in calls to sleep, see the fn rt
. Also, if you wish to bypass time scaling in synth args see use_arg_bpm_scaling
. See also with_bpm
for a block scoped version of use_bpm
.
For dance music here’s a rough guide for which BPM to aim for depending on your genre:
Introduced in v2.0
# Example 1 | |
|
|
use_bpm_mul mul (number)
Sets the tempo in bpm (beats per minute) as a multiplication of the current tempo. Affects all containing calls to sleep
and all temporal synth arguments which will be scaled to match the new bpm. See also use_bpm
Introduced in v2.3
# Example 1 | |
|
|
use_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_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_random_seed seed (number)
Resets the random number generator to the specified seed. All subsequently generated random numbers and randomisation functions such as shuffle
and choose
will use this new generator and the current generator is discarded. Use this to change the sequence of random numbers in your piece in a way that can be reproduced. Especially useful if combined with iteration. See examples.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
use_sample_bpm string_or_number (sample_name_or_duration)
Modify bpm so that sleeping for 1 will sleep for the duration of the sample.
Introduced in v2.1
num_beats: |
The number of beats within the sample. By default this is 1. |
# Example 1 | |
|
|
# Example 2 | |
|
|
use_sample_defaults
Specify new default values to be used by all subsequent calls to sample
. Will remove and override any previous defaults.
Introduced in v2.5
# Example 1 | |
|
|
use_sample_pack pack_path (string)
Given a path to a folder of samples on your filesystem, this method makes any .wav
, .wave
, .aif
or .aiff
files in that folder available as samples. Consider using use_sample_pack_as
when using multiple sample packs. Use use_sample_pack :default
To revert back to the default built-in samples.
Introduced in v2.0
# Example 1 | |
|
|
use_sample_pack_as path (string), alias (string)
Similar to use_sample_pack
except you can assign prefix aliases for samples. This lets you ‘namespace’ your sounds so that they don’t clash, even if they have the same filename.
Introduced in v2.0
# Example 1 | |
|
|
use_synth synth_name (symbol)
Switch the current synth to synth_name
. Affects all further calls to play
. See with_synth
for changing the current synth only for a specific do
/end
block.
Introduced in v2.0
# Example 1 | |
|
|
use_synth_defaults
Specify new default values to be used by all subsequent calls to play
. Will remove and override any previous defaults.
Introduced in v2.0
# Example 1 | |
|
|
use_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.
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_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_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 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_random_seed seed (number)
Resets the random number generator to the specified seed for the specified code block. All generated random numbers and randomisation functions such as shuffle
and choose
within the code block will use this new generator. Once the code block has completed, the original generator is restored and the code block generator is discarded. Use this to change the sequence of random numbers in your piece in a way that can be reproduced. Especially useful if combined with iteration. See examples.
Introduced in v2.0
# Example 1 | |
|
|
# Example 2 | |
|
|
with_sample_bpm string_or_number (sample_name_or_duration)
Block-scoped modification of bpm so that sleeping for 1 will sleep for the duration of the sample.
Introduced in v2.1
num_beats: |
The number of beats within the sample. By default this is 1. |
# Example 1 | |
|
|
# Example 2 | |
|
|
with_sample_defaults
Specify new default values to be used by all subsequent calls to sample
within the do
/end
block. After the do
/end
block has completed, the previous sampled defaults (if any) are restored. For the contents of the block, will remove and override any previous defaults.
Introduced in v2.5
# Example 1 | |
|
|
with_sample_pack pack_path (string)
Given a path to a folder of samples on your filesystem, this method makes any .wav
, .wave
, .aif
, or .aiff
files in that folder available as samples inside the given block. Consider using with_sample_pack_as
when using multiple sample packs.
Introduced in v2.0
# Example 1 | |
|
|
with_sample_pack_as pack_path (string)
Similar to with_sample_pack
except you can assign prefix aliases for samples. This lets you ‘namespace’ your sounds so that they don’t clash, even if they have the same filename.
Introduced in v2.0
# Example 1 | |
|
|
with_synth synth_name (symbol)
Switch the current synth to synth_name
but only for the duration of the do
/end
block. After the do
/end
block has completed, the previous synth is restored.
Introduced in v2.0
# Example 1 | |
|
|
with_synth_defaults
Specify new default values to be used by all calls to play
within the do
/end
block. After the do
/end
block has completed the previous synth defaults (if any) are restored.
Introduced in v2.0
# Example 1 | |
|
|
with_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.
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 | |
|
|