Trigger sample

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

Options

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 window_size:, pitch_dis: and time_dis: opts depending on the sample and the amount you’d like to stretch/shrink from original size.

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_attack_level.

cutoff_sustain_level:

The sustain cutoff (value of cutoff at sustain time) as a MIDI note. Default value is :cutoff_decay_level.

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

Examples

# Example 1

sample :perc_bell



# plays one of Sonic Pi's built in samples



# Example 2

sample '/home/yourname/path/to/a/sample.wav'



# plays a wav|wave|aif|aiff file from your local filesystem



# Example 3



sample :loop_amen
sleep sample_duration(:loop_amen)






sample :loop_amen, rate: 0.5
sleep sample_duration(:loop_amen, rate: 0.5)




sample :loop_amen, rate: 0.05
sleep sample_duration(:loop_amen, rate: 0.05)


# Let's play with the rate parameter
# play one of the included samples
 
# this sleeps for exactly the length of the sample
 
# Setting a rate of 0.5 will cause the sample to
#   a) play half as fast
#   b) play an octave down in pitch
#
# Listen:
 
 
 
# Setting a really low number means the sample takes
# a very long time to finish! Also it sounds very
# different to the original sound
 
 



# Example 4



sample :loop_amen, rate: -1
sleep sample_duration(:loop_amen, rate: 1) 

                                            
                                            
sample :loop_amen, rate: -0.5
sleep sample_duration(:loop_amen, rate: 0.5)



# Setting a really negative number can be lots of fun
# It plays the sample backwards!
 
# there's no need to give sample_duration a negative number though
 
# Using a rate of -0.5 is just like using the positive 0.5
# (lower in pitch and slower) except backwards
 
# there's no need to give sample_duration a negative number though



# Example 5





puts sample_duration(:loop_amen, rate: 0)


# BE CAREFUL
# Don't set the rate to 0 though because it will get stuck
# and won't make any sound at all!
# We can see that the following would take Infinity seconds to finish
 



# Example 6






s = sample :loop_amen_full, rate: 0.05
sleep 1
control(s, rate: 0.2)
sleep 1
control(s, rate: 0.4)
sleep 1
control(s, rate: 0.6)
sleep 1
control(s, rate: 0.8)
sleep 1
control(s, rate: 1)


# Just like the play method, we can assign our sample player
# to a variable and control the rate parameter whilst it's playing.
#
# The following example sounds a bit like a vinyl speeding up
# Note, this technique only works when you don't use envelope or start/finish opts.
 
 
 
 
 
 
 
 
 
 
 



# Example 7



sample :loop_amen, start: 0.5, finish: 1



# Using the :start and :finish parameters you can play a section of the sample.
# The default start is 0 and the default finish is 1
# play the last half of a sample



# Example 8



sample :loop_amen, start: 1, finish: 0.5



# You can also play part of any sample backwards by using a start value that's
# higher than the finish
# play the last half backwards



# Example 9


sample {sample_name: :loop_amen, rate: 2}


# You can also specify the sample using a Hash with a `:sample_name` key
 



# Example 10



sample lambda { [:loop_amen, :loop_garzul].choose }


# You can also specify the sample using a lambda that yields a symbol
# although you probably don't need a lambda for this in most cases.