Skip to main content

el.sample([props], t, rate)

Loads a sample from disk and triggers its playback on the rising edge of an incoming pulse train. Expects two children: first the pulse train to trigger playback, and second a signal which continuously directs the sample's playback rate. For example,

el.sample({path: 'kick.wav'}, el.train(1), 1);   // Equivalent to the default playback
el.sample({path: 'kick.wav'}, el.train(1), 0.5); // Half speed playback
el.sample({path: 'kick.wav'}, el.train(1), el.add(1, el.cycle(1))); // Continuous pitch modulation

Because each Elementary node has strictly one channel output, the channel prop can be used to decide which channel from the sample to propagate. In the example below, if kick.wav is a stereo wav file sample, the sample node here will only play the right channel.

Example:

el.sample({path: '/path/to/kick.wav', channel: 1}, el.train(1));

Props

NameDefaultTypeDescription
path''String*The location of the sample file
channel0Number*The channel to read from the sample file
datanullArray or Float32Array*Raw buffer data to load the sample from
mode'trigger'StringOne of "trigger", "gate", "loop"
startOffset0NumberOffset in samples from the start of the sample where playback starts
stopOffset0NumberOffset in samples from the end of the sample where playback ends
  • Note: the path, channel, and data prop are all related in that their job is to provide a resource from which to load the sample player.
    • Providing a path property will first attempt to look the file up in the pre-loaded virtual file system, then fall back to a disk-read if running on a target that has disk access (i.e. the Plugin Dev Kit).
    • When falling back to a read from disk, the channel property will specify which channel from a multi-channel sample file to load. el.sample outputs a mono signal, so you must choose which channel you want to read from the underlying file.
    • When providing the data property, you'll pass either an Array or a Float32Array containing the raw sample buffer to be loaded into the sampler. This is a great solution for a quick hack or a small array, but any large arrays should preferably be loaded into the virtual file system ahead of time.
    • Behavior is undefined when both the path and the channel prop are provided.

Mode prop

A brief elaboration on the available playback modes:

  • gate means that sample playback will start from startOffset on the rising edge of the incoming pulse train, and will stop on the subsequent falling edge.
  • trigger mode means that sample playback will start from startOffset on the rising edge of the incoming pulse train and will not stop on the subsequent falling edge.
  • loop mode means that the sample will continuously loop between startOffset and stopOffset as long as the incoming pulse train is high.