Source code for audiooscillator

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""A band-limited oscillator that other audio streams can steer.

`Oscillator` reads its pitch, linear FM, pulse width and hard sync from audio
streams every sample, so one oscillator can sync to another or be
frequency-modulated by it. `synthio` moves its pitch once per block and reads
a wavetable with no band limiting; this oscillator does neither. Steps are
band-limited with PolyBLEP and the triangle's corners with PolyBLAMP.
"""

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

SAW: int
"""A waveform: a rising sawtooth. Waveforms add: pass ``SAW + PULSE`` to mix
the two from the same phase."""
PULSE: int
"""A waveform: a pulse wave whose width is ``pulse_width``."""
TRIANGLE: int
"""A waveform: a triangle."""
SINE: int
"""A waveform: a sine."""

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

[docs] class Oscillator: """A band-limited oscillator, played like any audio sample. The output trails the phase by one sample, which lets a sync edge, which nothing can see coming, still correct the sample before it. The first block holds the waveform's value at phase zero. Every argument is a keyword. The inputs are audio samples, mono or stereo, read one frame per output frame; a stereo input is read from its first channel. An input that is left out or None does nothing. Args: sample_rate: Frames per second, 1 or more. channel_count: 1 or 2. buffer_size: Bytes in one block, a whole number of frames, from one frame to 256 frames. The default is 256 frames. frequency: The pitch in Hz before the ``pitch`` input moves it. The default is 440.0. The phase step is limited to between a tenth of a sample and just under half the rate. waveform: A sum of `SAW`, `PULSE`, `TRIANGLE` and `SINE`. The default is `SAW`. waveform_right: The right channel's waveform, from the same phase. The default is `SAW`. Used only when ``channel_count`` is 2. pulse_width: The pulse's width as a fraction of the cycle, 0.05 to 0.95. The default is 0.5. level: The output for a waveform's full swing, where 1.0 is full scale. The default is 1.0. pitch_octaves: Octaves the ``pitch`` input moves the pitch for a full-scale signal. The default is 10.0. fm_depth: Hz the ``fm`` input moves the frequency for a full-scale signal, linearly. The default is 0.0. pwm_depth: Pulse width the ``pwm`` input adds for a full-scale signal. The default is 0.5. pitch: An audio sample that moves the pitch exponentially. fm: An audio sample that frequency-modulates the oscillator. pwm: An audio sample that modulates the pulse width. sync: An audio sample that resets the phase when it rises through zero. Raises: TypeError: An unknown keyword was given, or an input is not an audio sample. ValueError: ``sample_rate`` is below 1, ``channel_count`` is not 1 or 2, ``buffer_size`` is not valid, or an input has more than two channels. """ def __init__( self, *, sample_rate: int = 48000, channel_count: int = 1, buffer_size: int | None = None, frequency: float = ..., waveform: int = ..., waveform_right: int = ..., pulse_width: float = ..., level: float = ..., pitch_octaves: float = ..., fm_depth: float = ..., pwm_depth: float = ..., pitch: _AudioSample | None = None, fm: _AudioSample | None = None, pwm: _AudioSample | None = None, sync: _AudioSample | None = None, ) -> 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."""
[docs] def set( self, *, frequency: float = ..., waveform: int = ..., waveform_right: int = ..., pulse_width: float = ..., level: float = ..., pitch_octaves: float = ..., fm_depth: float = ..., pwm_depth: float = ..., ) -> None: """Change options while the oscillator plays. The options are those of the constructor, and all of them change together or not at all. Raises: TypeError: An unknown option was given. """
[docs] def modulate( self, *, pitch: _AudioSample | None = ..., fm: _AudioSample | None = ..., pwm: _AudioSample | None = ..., sync: _AudioSample | None = ..., ) -> None: """Connect or disconnect input streams while the oscillator plays. Inputs you do not name stay as they are; pass None to disconnect one. Raises: TypeError: An unknown input was named, or one is not an audio sample. ValueError: An input has more than two channels. """
[docs] def clear(self) -> None: """Set the phase back to zero."""
[docs] def deinit(self) -> None: """Release the oscillator and let go of its inputs. Every later use raises `ValueError`."""
def __enter__(self) -> Self: ... def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, /) -> None: ...