soir

OVERVIEW

The sampler module can be used on loops running on tracks with

instrument type set to sampler.

@public

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.

s = sampler.new('808')

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

CLASS

Kit

Kit(sp: soir.rt.sampler.Sampler)

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.

Methods

play
play(self, flavor: str) -> None

Play a sequence of samples defined by the flavor.

Arguments
Name Type Description
flavor str The name of the sequence flavor to play.
Raises
Exception Description
ValueError If the flavor does not exist in the patterns.
seq
seq(self, flavor: str, sequences: list[str]) -> None

Define a sequence of samples for a given flavor.

Arguments
Name Type Description
flavor str The name of the sequence flavor.
sequences list[str] A list of strings, each representing a sequence of characters.
Raises
Exception Description
ValueError If the sequences are not of the same length.
set
set(self, char: str, mkplay: Callable[[], dict[str, Any]]) -> None

Set a character to a sample play function.

Arguments
Name Type Description
char str The character that will trigger the sample.
mkplay callable A function that returns a dictionary of sample parameters.
↑ back to top

Sample

Sample(name: str, pack: str, path: str, duration: float) -> None

Represents a sample from a sample pack.

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.

Arguments

Name Type Description
name The name of the sample.
pack The name of the pack.
path The location of the sample file.
duration The length of the sample in seconds.
↑ back to top

Sampler

Sampler(pack_name: str)

A sampler allows playing samples from a given sample pack.

Use the shortcut sampler.new() to create a Sampler.

Methods

play
play(self, name: str = '', start: float = 0.0, end: float = 1.0, pan: float | soir.rt.ctrls.Control = 0.0, attack: float = 0.0, decay: float = 0.0, sustain: float | None = None, level: float = 1.0, release: float = 0.0, rate: float = 1.0, amp: float = 1.0) -> None

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.

Arguments
Name Type Description
name The name of the sample.
start When in the sample to start playing in the [0.0, 1.0] range.
end When in the sample to end playing in the [0.0, 1.0] range.
pan The panning of the sample in the [-1.0, 1.0] range, or a control.
attack The attack time in seconds.
decay The decay time in seconds.
sustain The sustain time in seconds, infered from the sample duration if None.
release The release time in seconds.
level The sustain level in the [0.0, 1.0] range.
rate The playback rate of the sample.
amp The amplitude of the sample.
stop
stop(self, name: str) -> None

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

Arguments
Name Type Description
name The name of the sample.
↑ back to top

FUNCTION

new

new(pack_name: str) -> 'Sampler'

Creates a new sampler with samples from the designated pack.

Arguments

Name Type Description
pack_name The name of the sample pack to use.
↑ back to top

packs

packs() -> list[str]

Returns the list of available sample packs.

Returns

– The list of loaded sample packs.

↑ back to top

samples

samples(pack_name: str) -> list[soir.rt.sampler.Sample]

Returns the list of samples available in the given pack.

Arguments

Name Type Description
pack_name The name of the sample pack.

Returns

– The list of samples from the sample pack.

↑ back to top