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: parameter affects both the speed and the pitch of the playback. See the examples for details. 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 low pass filter (lpf) in MIDI notes. Unless specified, the lpf is not added to the signal chain.

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