<commit_before>---
title: Loading and using a sampler
---

A sampler is an instrument which stores chunks of audio which can be
*triggered*---played back. Samplers are used in many different ways, such as
providing digital simulations of acoustic instruments (e.g. a piano sampler
which plays recorded samples of a *real* piano when triggered by messages from a
MIDI keyboard) or they can be used to play and manipulate non-acoustic sounds.

Since samplers are so useful, Extempore provides a built-in sampler in
`libs/external/instruments_ext.xtm`. This sampler basically works like any other
Extempore instrument, except that the note kernel closure is already set up for
you---you just have to load the sampler with sound files. There is also a slight
difference in the way we set a sampler up: using the Scheme macro
`make-instrument`. The Extempore sampler is still an xtlang closure, and can be
used in all the same situations (e.g. as the `inst` argument to `play-note` or
`play`) as an instrument can.

## Samplers 101 {#samplers-101}

You can think of a sampler as a series of 'slots', each of which contains a
sound file.

![image](/images/sampler/piano-full.png)

Each slot has a unique index, and playing the sampler generally involves
specifying the index of the sample to play, the loudness/velocity and the
duration. There are lots of subtleties to this process, such as what to do when
the duration is longer than the sample length, what to do if there isn't a
sample at the given index, etc., but at a high level that's how it works.

If you look at the filenames in each slot (although it's the audio *data* in the
slots, not the filename strings), you'll notice that they refer to
[wave](http://en.wikipedia.org/wiki/WAV) (audio) files named with [scientific
pitch notation](http://en.wikipedia.org/wiki/Scientific_pitch_notation). These
wave files could be recordings of a piano, or of a violin, or even of abstract
sound effects (although at that point we'd have to wonder why they were named
with pitches from the musical scale). The sampler doesn't care what audio data
is stored in each slot, and it's up to you to make sure that both the slot the
audio is stored in and the audio data itself make sense for whatever musical
purpose you have in mind.

For sampling pitched instruments, using [MIDI note
numbers](http://www.phys.unsw.edu.au/jw/notes.html) (middle C = 60) make sense,
and that's the convention I've used in the diagram above. If you want to trigger
the sample for middle C, just use `play-note` with a pitch argument of `60`.

The Extempore sampler doesn't *have* to be full---there can be empty slots.

![image](/images/sampler/piano-gaps.png)

In this situation, when the sampler gets a `play-note` message corresponding to
an empty slot, looks for the closest 'filled' slot, grabs that audio data, and
linearly pitch-shifts it to play at the required pitch.

For example, say a message came in to play sample `72` (one octave above middle
C). If the closest filled slot was middle C (slot `60`), then the sampler would
play the middle C audio file pitch-shifted up one octave. If you've ever looked
into the maths behind musical notes, you'll know that for every octave increase
in pitch, the frequency of the waveform doubles. So, to play a sample *up an
octave*, we play it back at double speed. In practice, because the audio sample
rate is constant, we only play every second sample, which has the same
effect---we're progressing through the audio data twice as fast. This is the
same reason that when you hit fast-forward on a tape player (do people still<commit_msg>clean up some language<commit_after>---
title: Loading and using a sampler
---

A sampler is an instrument which stores chunks of audio which can be
*triggered*---played back. Samplers are used in many different ways, such as
providing digital simulations of acoustic instruments (e.g. a piano sampler
which plays recorded samples of a *real* piano when triggered by messages from a
MIDI keyboard) or they can be used to play and manipulate non-acoustic sounds.
Since samplers are so useful, Extempore provides a built-in sampler in
`libs/external/instruments_ext.xtm`.

## Samplers 101 {#samplers-101}

You can think of a sampler as a series of 'slots', each of which contains a
sound file.

![image](/images/sampler/piano-full.png)

Each slot has a unique index, and playing the sampler generally involves
specifying the index of the sample to play, the loudness/velocity and the
duration. There are lots of subtleties to this process, such as what to do when
the duration is longer than the sample length, what to do if there isn't a
sample at the given index, etc., but at a high level that's how it works.

If you look at the filenames in each slot (although it's the audio *data* in the
slots, not the filename strings), you'll notice that they refer to
[wave](http://en.wikipedia.org/wiki/WAV) (audio) files named with [scientific
pitch notation](http://en.wikipedia.org/wiki/Scientific_pitch_notation). These
wave files could be recordings of a piano, or of a violin, or even of abstract
sound effects (although at that point we'd have to wonder why they were named
with pitches from the musical scale). The sampler doesn't care what audio data
is stored in each slot, and it's up to you to make sure that both the slot the
audio is stored in and the audio data itself make sense for whatever musical
purpose you have in mind.

For sampling pitched instruments, using [MIDI note
numbers](http://www.phys.unsw.edu.au/jw/notes.html) (middle C = 60) make sense,
and that's the convention I've used in the diagram above. If you want to trigger
the sample for middle C, just use `play-note` with a pitch argument of `60`.

The Extempore sampler doesn't *have* to be full---there can be empty slots.

![image](/images/sampler/piano-gaps.png)

In this situation, when the sampler is told to play a pitch value corresponding
to an empty slot, looks for the closest 'filled' slot, grabs that audio data,
and linearly pitch-shifts it to play at the required pitch.

For example, say the sampler is told to play sample `72` (one octave above
middle C). If the closest filled slot was middle C (slot `60`), then the sampler
would play the middle C audio file pitch-shifted up one octave. If you've ever
looked into the maths behind musical notes, you'll know that for every octave
increase in pitch, the frequency of the waveform doubles. So, to play a sample
*up an octave*, we play it back at double speed. In practice, because the audio
sample rate is constant, we only play every second sample, which has the same
effect---we're progressing through the audio data twice as fast. This is the
same reason that when you hit fast-forward on a tape player (do people still
{'fraction_non_alphanumeric': 0.06134788379295089, 'fraction_numerical': 0.004129184486064003, 'mean_word_length': 4.281931464174455, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2190167', 'n_tokens_mistral': 1892, 'n_tokens_neox': 1792, 'n_words': 1088}