Source code for audiomath

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Arithmetic on audio streams.

`Multiply` multiplies one stream by another, which is ring and amplitude
modulation. `SubOctave` divides a stream down in frequency, as an analog
octave divider does. `remix_s16` changes between mono and stereo, and
`cast_into` turns a block of floats into the 16-bit buffer a `RawSample`
plays, without allocating.

Both nodes are audio samples, so they play wherever a `RawSample` does and
take any audio sample as their source.
"""

from __future__ import annotations
from types import TracebackType
from typing import Protocol, 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."""

class _AudioSample(Protocol):
    @property
    def sample_rate(self) -> int: ...
    @property
    def bits_per_sample(self) -> int: ...
    @property
    def channel_count(self) -> int: ...

[docs] class Multiply: """Multiplies a stream by a modulator, sample by sample. The output is the source blended toward the source times the modulator: ``mix`` 1.0 is the full product and 0.0 is the source untouched. With no modulator, or after the modulator has run dry, the source passes through unchanged rather than going silent. With no source, the node outputs silence and never reports itself finished. The source and the modulator must have this node's channel count. Output is 16-bit signed. Args: source: The stream to modulate, or None to set it later with `play`. modulator: The stream to multiply by, or None to set it later with `modulate`. A short looping table such as a sine in a `RawSample` is the usual choice. mix: Wet amount from 0.0 to 1.0, clamped. The default is 1.0. sample_rate: Frames per second. channel_count: 1 or 2. Raises: ValueError: ``channel_count`` is not 1 or 2, or a stream's channel count differs from it. """ def __init__( self, source: _AudioSample | None = None, modulator: _AudioSample | None = None, mix: float | None = None, sample_rate: int = 48000, channel_count: int = 2, ) -> None: ... @property def sample_rate(self) -> int: """Frames per second.""" @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."""
[docs] def play(self, source: _AudioSample, /) -> None: """Replace the stream being modulated. Raises: ValueError: The stream's channel count differs from this node's. """
[docs] def modulate(self, modulator: _AudioSample, /) -> None: """Replace the stream that multiplies the source. Raises: ValueError: The stream's channel count differs from this node's. """
[docs] def set(self, *, mix: float = ...) -> None: """Change an option while the node plays. A move of ``mix`` on a playing node walks to the new value in a straight line over 20 ms instead of stepping, so it doesn't click. Before the first pull, or after a reset, it lands at once. Args: mix: Wet amount from 0.0 to 1.0, clamped. Raises: TypeError: An option other than ``mix`` was given. """
[docs] def deinit(self) -> None: """Release the node and let go of its source and modulator. Every later use raises `ValueError`."""
def __enter__(self) -> Self: ... def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, /) -> None: ...
[docs] class SubOctave: """An analog-style octave divider. A Schmitt trigger watches the source for rising edges and two flip-flops halve the count, so the output is a square wave one or two octaves below the input's pitch, blended with the dry signal by ``mix``. It works best on a single note: filter a chord to its fundamental first. Args: source: The stream to divide, or None to set it later with `play`. Its channel count must match this node's. order: 1 for one octave down, 2 for two. Any value of 2 or more means 2. mix: How much of the divided signal replaces the dry signal, 0.0 to 1.0, clamped. The default is 1.0. threshold: How far from zero the comparator's two thresholds sit, as a fraction of full scale, 0.0 to 1.0, clamped. Signal between them leaves the comparator where it is. 0.0 is a bare zero-crossing detector. hold_ms: Milliseconds after an accepted edge during which another is ignored, to keep noise from counting twice. Negative values mean 0. sample_rate: Frames per second, 1 or more. channel_count: 1 or 2. Raises: ValueError: ``channel_count`` is not 1 or 2, ``sample_rate`` is below 1, or the source's channel count differs. """ def __init__( self, source: _AudioSample | None = None, order: float | None = None, mix: float | None = None, threshold: float | None = None, hold_ms: float | None = None, sample_rate: int = 48000, channel_count: int = 2, ) -> None: ... @property def sample_rate(self) -> int: """Frames per second.""" @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."""
[docs] def play(self, source: _AudioSample, /) -> None: """Replace the stream being divided. Raises: ValueError: The stream's channel count differs from this node's. """
[docs] def set( self, *, order: float = ..., mix: float = ..., threshold: float = ..., hold_ms: float = ..., ) -> None: """Change options while the node plays. The count keeps running, so a change never flips the output's polarity. Args: order: As for the constructor. mix: As for the constructor. threshold: As for the constructor. hold_ms: As for the constructor. Raises: TypeError: An unknown option was given. """
[docs] def clear(self) -> None: """Reset the comparator and the dividers to where a new node starts."""
[docs] def deinit(self) -> None: """Release the node and let go of its source. Every later use raises `ValueError`."""
def __enter__(self) -> Self: ... def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, /) -> None: ...
[docs] def remix_s16( source: bytes | bytearray | memoryview, src_channels: int, dst_channels: int, dest: bytearray | memoryview | None = None, /, ) -> bytearray | memoryview: """Convert interleaved 16-bit audio between mono and stereo. Args: source: Signed 16-bit samples, a whole number of frames. src_channels: The source's channel count, 1 or 2. dst_channels: The channel count wanted, 1 or 2. dest: A buffer to write into, at least as long as the result. Leave it out to get a new `bytearray`. Returns: ``dest``, or the new `bytearray` when ``dest`` was left out. Raises: ValueError: A channel count is not 1 or 2, ``source`` is not a whole number of frames, or ``dest`` is too small. """
[docs] def cast_into(dst: bytearray | memoryview, src: object, scale: float = 32767.0) -> None: """Convert a block of floats into 16-bit samples without allocating. Each value is multiplied by ``scale``, rounded half away from zero and saturated to the 16-bit range. Args: dst: Where to write: a buffer of signed 16-bit samples, as many as ``src`` has floats. src: A buffer of 32-bit or 64-bit floats, such as an `array.array` of type ``'f'`` or ``'d'``. scale: What a value of 1.0 becomes. Raises: TypeError: ``dst`` is not a 16-bit buffer or ``src`` is not floats. ValueError: ``dst`` and ``src`` hold a different number of samples. """