📼 sampler

sampler

Info

The sampler module can be used on loops running on tracks with instrument type set to sampler.

The sampler module provides a way to load samples and play them inside loops in an intuitive way. Once instantiated, a Sampler can be used to play samples from the selected pack given their name. If no exact match of the sample name is found, the first matching sample is selected. The cost of creating and using a sampler is cheap so it is fine to have a lot of instances at once.

Cookbook

Play samples

s = sampler.new('808')

@loop
def kick(beats=4):
  for i in range(4):
    s.play('kick')
    sleep(1)

List available packs

packs = sampler.packs()

List samples in a pack

samples = sampler.samples('808')

Reference

Classes:

Name	Description
Kit	A simple kit for playing patterns of samples.
Sample	A sample is a sound file that can be played by a sampler. It has a
Sampler

Functions:

Name	Description
new	Creates a new sampler with samples from the designated pack.
packs	Returns the list of available sample packs.
samples	Returns the list of samples available in the given pack.

Kit(sp)

A simple kit for playing patterns of samples.

This class allows you to define a set of samples (or "plays") that can be triggered by characters, and then create sequences of these characters to play patterns.

Example usage:

sp = sampler.new('my-sample-pack')

kit = sampler.Kit(sp)

kit.set('k', lambda: {'name': 'bd-808'})
kit.set('s', lambda: {'name': 'sd-808'})

kit.seq('basic', [
    'k-------k-------',
    '--------s-------',
])

kit.play('basic')

This will play a basic kick and snare pattern using the defined samples.

Initialize the Kit with a sampler instance.

Parameters:

Name	Type	Description	Default
sp	Sampler	The sampler instance to use for playing samples.	required

Methods:

Name	Description
play	Play a sequence of samples defined by the flavor.
seq	Define a sequence of samples for a given flavor.
set	Set a character to a sample play function.

play(flavor)

Play a sequence of samples defined by the flavor.

Parameters:

Name	Type	Description	Default
flavor	str	The name of the sequence flavor to play.	required

Raises: ValueError: If the flavor does not exist in the patterns.

seq(flavor, sequences)

Define a sequence of samples for a given flavor.

Parameters:

Name	Type	Description	Default
flavor	str	The name of the sequence flavor.	required
sequences	list[str]	A list of strings, each representing a sequence of characters.	required

Raises: ValueError: If the sequences are not of the same length.

set(char, mkplay)

Set a character to a sample play function.

Parameters:

Name	Type	Description	Default
char	str	The character that will trigger the sample.	required
mkplay	callable	A function that returns a dictionary of sample parameters.	required

Sample(name, pack, path, duration) dataclass

A sample is a sound file that can be played by a sampler. It has a name, a pack, a path, and a duration. The name is the identifier used to play the sample, the pack is the name of the pack the sample belongs to, the path is the location of the sample file, and the duration is the length of the sample in seconds.

Attributes:

Name	Type	Description
name	str	The name of the sample.
pack	str	The name of the pack.
path	str	The location of the sample file.
duration	float	The length of the sample in seconds.

Sampler(pack_name)

Creates a new sampler with samples from the designated pack.

Note

You can create a Sampler via the shortcut n.sampler.new().

Parameters:

Name	Type	Description	Default
pack_name	str	The name of the sample pack to use.	required

Methods:

Name	Description
play	Plays a sample by its given name. If there is no exact
stop	Stops playing the sample. If there is no exact match,

play(name='', start=0.0, end=1.0, pan=0.0, attack=0.0, decay=0.0, sustain=None, level=1.0, release=0.0, rate=1.0, amp=1.0)

Plays a sample by its given name. If there is no exact match, attempts to find one that contains the name (for example, 'kick' will match 'hard-kick'). If the selected sample is already being played, enqueues a new one, allowing to play simultaneously multiple times the same sample.

Parameters:

Name	Type	Description	Default
name	str	The name of the sample.	''
start	float	When in the sample to start playing in the [0.0, 1.0] range.	0.0
end	float	When in the sample to end playing in the [0.0, 1.0] range.	1.0
pan	float | Control	The panning of the sample in the [-1.0, 1.0] range, or a control.	0.0
attack	float	The attack time in seconds.	0.0
decay	float	The decay time in seconds.	0.0
sustain	float | None	The sustain time in seconds, infered from the sample duration if None.	None
release	float	The release time in seconds.	0.0
level	float	The sustain level in the [0.0, 1.0] range.	1.0
rate	float	The playback rate of the sample.	1.0
amp	float	The amplitude of the sample.	1.0

stop(name)

Stops playing the sample. If there is no exact match, attempts to find one that contains the name (for example, 'kick' will match 'hard-kick'). If the same sample is currently played multiple times, the latest one is selected to stop (LIFO).

Parameters:

Name	Type	Description	Default
name	str	The name of the sample.	required

new(pack_name)

Creates a new sampler with samples from the designated pack.

Parameters:

Name	Type	Description	Default
pack_name	str	The name of the sample pack to use.	required

packs()

Returns the list of available sample packs.

Returns:

Type	Description
list[str]	The list of loaded sample packs.

samples(pack_name)

Returns the list of samples available in the given pack.

Parameters:

Name	Type	Description	Default
pack_name	str	The name of the sample pack.	required

Returns:

Type	Description
list[Sample]	The list of samples from the sample pack.