Source code for audiosampler

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Recorded notes, played at any pitch.

`Sampler` is an audio source with a fixed number of voices. A voice plays a
recording of a note at any pitch, loops a region of it while the key is held,
and lets the rest out when the key lifts, under an amplitude envelope with an
optional resonant low-pass filter, a modulation envelope and two LFOs. That
is what a SoundFont instrument and a drum machine need, and what
`audiomixer.Mixer` (which plays sources at their own rate) and `synthio`
(which plays single-cycle waveforms) cannot do.

`SampleBuffer` holds samples in memory outside the collected heap, so a bank
of many megabytes does not slow every garbage collection.

All voices are mixed in one C call per block, through a 4-point Hermite
interpolator.
"""

from __future__ import annotations
from types import TracebackType
from typing import Self

__version__: str
"""The audiodsp release this module came from."""
__revision__: str
"""Which source this build was made from, from `git describe`: a release tag,
or the nearest one and the commit. "unknown" when the build had no git."""

FRAMES: int
"""Frames in one block when ``buffer_size`` is not given: 256."""
MAX_FRAMES: int
"""The most frames in one block: 1024."""
MAX_VOICES: int
"""The most voices a `Sampler` can have: 128."""
LOOP_NONE: int
"""A loop mode: play to the end of the buffer and stop. This is SoundFont's
``sampleModes`` value 0."""
LOOP_FOREVER: int
"""A loop mode: loop ``[loop_start, loop_end)`` until `SamplerVoice.release`
or `SamplerVoice.stop`. This is SoundFont's ``sampleModes`` value 1."""
LOOP_UNTIL_RELEASE: int
"""A loop mode: loop while the key is held, then play on past the loop to the
end of the buffer. This is SoundFont's ``sampleModes`` value 3."""

[docs] class SampleBuffer: """Zeroed memory for samples, outside the collected heap. Read audio into it, or copy it in, and play views of it with `SamplerVoice.play`. The memory comes from PSRAM on boards whose audio driver says where, and from the system allocator elsewhere. A `memoryview` of a buffer does not keep it alive. Hold the buffer itself for as long as a voice plays from it. Args: size: Bytes to allocate and zero. Raises: ValueError: ``size`` is negative. MemoryError: The bytes could not be allocated. """ def __init__(self, size: int, /) -> None: ... def __len__(self) -> int: """The size in bytes, which is 0 after `deinit`.""" def __buffer__(self, flags: int, /) -> memoryview: ...
[docs] def deinit(self) -> None: """Free the bytes at once. The buffer then has a length of 0."""
def __enter__(self) -> Self: ... def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, /) -> None: ...
[docs] class SamplerVoice: """One voice of a `Sampler`. Get voices from `Sampler.voice`; they cannot be made on their own. A voice plays one note at a time. Starting a new note on a sounding voice fades the old one out over 5 ms. """ level: float """The voice's level, where 1.0 is unity gain. It is limited to 0.0 to 1.0 when applied, and reads back as you set it. A live setting: the change lands at the next block, as a ramp across it, so a fader move does not click.""" pan: float """Position in the stereo field from -1.0 (left) to 1.0 (right), limited to that range when applied. A live setting, ramped like `level`.""" pitch: float """Playback speed as a ratio, 1.0 for the recording's own pitch, from 1/64 to 64 (clamped). A live setting, which is how a pitch bend is played.""" cutoff: float | None """The low-pass filter's cutoff in Hz, or None for no filter. A live setting: a change lands within 32 frames, and a filter switched on starts from rest.""" vibrato_depth: float """The vibrato LFO's depth in cents. A live setting, so a mod wheel is a series of writes here; each lands within 32 frames.""" @property def playing(self) -> bool: """Whether the voice still sounds."""
[docs] def play( self, buffer: bytes | bytearray | memoryview | SampleBuffer, *, rate: float | None = None, pitch: float | None = None, loop_start: int = 0, loop_end: int | None = None, loop_mode: int = 0, level: float | None = None, pan: float | None = None, delay: float | None = None, attack: float | None = None, hold: float | None = None, decay: float | None = None, sustain: float | None = None, release: float | None = None, cutoff: float | None = None, resonance: float | None = None, mod_delay: float | None = None, mod_attack: float | None = None, mod_hold: float | None = None, mod_decay: float | None = None, mod_sustain: float | None = None, mod_release: float | None = None, mod_to_pitch: float | None = None, mod_to_cutoff: float | None = None, vibrato_delay: float | None = None, vibrato_rate: float | None = None, vibrato_depth: float | None = None, lfo_delay: float | None = None, lfo_rate: float | None = None, lfo_to_pitch: float | None = None, lfo_to_cutoff: float | None = None, lfo_to_volume: float | None = None, ) -> None: """Start a note. The buffer is held for as long as the voice sounds and let go when it stops. The step per output frame is ``pitch * rate / sample_rate``, so a 44.1 kHz recording plays at the right speed through a 48 kHz output without being told anything else. Every option except ``buffer`` is a keyword, and None (the default) means the value given here. Args: buffer: The recording: mono signed 16-bit samples, in a buffer holding at least one whole sample. rate: The recording's own sample rate in Hz. The default is the sampler's. pitch: Playback speed as a ratio. The default is 1.0. loop_start: The first frame of the loop. loop_end: The frame after the last one of the loop. The default is the end of the buffer. loop_mode: `LOOP_NONE`, `LOOP_FOREVER` or `LOOP_UNTIL_RELEASE`. level: Level from 0.0 to 1.0, where 1.0 is unity gain. The default is 1.0. pan: Stereo position, -1.0 to 1.0. The default is 0.0. delay: Seconds before the sound starts, which is what a flam wants. The default is 0.0. attack: Amplitude envelope attack time in seconds. The default is 0.0. hold: Amplitude envelope hold time in seconds. The default is 0.0. decay: Amplitude envelope decay time in seconds. The default is 0.0. sustain: Amplitude envelope sustain level, linear. The default is 1.0. release: Amplitude envelope release time in seconds. The default is 0.0. cutoff: Low-pass cutoff in Hz. A cutoff of 19.9 kHz or more, with no resonance and nothing moving it, is no filter at all, and so is leaving it out. resonance: The filter's response at the cutoff above its response at DC, in dB, from 0 to 96. DC drops by half of it, as the SoundFont specification puts it. 0 is a Butterworth. mod_delay: The modulation envelope's delay in seconds. This envelope has the amplitude envelope's six stages and moves pitch and cutoff. The default is 0.0. mod_attack: Its attack time in seconds. The default is 0.0. mod_hold: Its hold time in seconds. The default is 0.0. mod_decay: Its decay time in seconds. The default is 0.0. mod_sustain: Its sustain level, linear. The default is 1.0. mod_release: Its release time in seconds. The default is 0.0. mod_to_pitch: How far the modulation envelope moves the pitch at full scale, in cents. The default is 0.0. mod_to_cutoff: How far it moves the cutoff at full scale, in cents. The default is 0.0. vibrato_delay: Seconds before the vibrato LFO starts. The default is 0.0. vibrato_rate: The vibrato LFO's rate in Hz. The default is 0.0. vibrato_depth: The vibrato LFO's depth in cents, moving the pitch. The default is 0.0. lfo_delay: Seconds before the modulation LFO starts. The default is 0.0. lfo_rate: The modulation LFO's rate in Hz. The default is 0.0. lfo_to_pitch: How far the modulation LFO moves the pitch at its peak, in cents. The default is 0.0. lfo_to_cutoff: How far it moves the cutoff at its peak, in cents. The default is 0.0. lfo_to_volume: How far it moves the level at its peak, in dB. The default is 0.0. Raises: ValueError: ``buffer`` holds less than one whole 16-bit sample, ``loop_start`` or ``loop_end`` is negative, ``loop_mode`` is not one of the three, the loop does not fit the buffer, or the sampler was deinitialised. """
[docs] def release(self) -> None: """Let the key go: enter the release stage from wherever the envelope is. In `LOOP_UNTIL_RELEASE` the voice also stops looping and plays on to the end."""
[docs] def stop(self) -> None: """Free the voice at once. The note fades out over 5 ms rather than being cut."""
[docs] def deinit(self) -> None: """Stop the voice with no fade and let go of its buffer. The voice belongs to its sampler, which keeps working."""
def __enter__(self) -> Self: ... def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, /) -> None: ...
[docs] class Sampler: """A bank of sample-playing voices, played like any audio sample. The output is signed 16-bit. Notes start on `voice`. Args: voice_count: How many voices, 1 to `MAX_VOICES`. buffer_size: Bytes in one block, a whole number of frames up to `MAX_FRAMES`. 0 means `FRAMES` frames. channel_count: 1 or 2. bits_per_sample: Only 16 is accepted. The argument exists so a sampler can stand where a mixer stood. samples_signed: Only True is accepted, for the same reason. sample_rate: Frames per second, 1 or more. Raises: ValueError: An argument is out of range, or ``bits_per_sample`` or ``samples_signed`` asks for anything but signed 16-bit. """ def __init__( self, *, voice_count: int = 8, buffer_size: int = 0, channel_count: int = 2, bits_per_sample: int = 16, samples_signed: bool = True, sample_rate: int = 48000, ) -> None: ... sample_rate: int """Frames per second. Writable, to 1 or more.""" @property def bits_per_sample(self) -> int: """Size of one sample in bits: always 16.""" @property def channel_count(self) -> int: """Number of channels: 1 or 2.""" @property def voice(self) -> tuple[SamplerVoice, ...]: """The voices, as a tuple of `voice_count` `SamplerVoice` objects.""" @property def voice_count(self) -> int: """How many voices the sampler has.""" @property def playing(self) -> bool: """Whether any voice sounds, a stopped note's fade included."""
[docs] def stop(self) -> None: """Stop every voice, each with the 5 ms fade of `SamplerVoice.stop`."""
[docs] def deinit(self) -> None: """Stop every voice and let go of every buffer. Every later use raises `ValueError`."""
def __enter__(self) -> Self: ... def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, /) -> None: ...