SonicLab

SonicLab is a modular Python DSP / audio synthesis engine: vectorized oscillators, envelopes, filters, effects, sequencing, optional realtime audio I/O, and MIDI adapters.

Status: Beta. Public APIs may still evolve; see docs/stability.md and CHANGELOG.md.

Features

• Oscillators: sine, square, sawtooth, triangle, PolyBLEP bandlimited variants
• Modulation: ADSR / decay envelopes, modulated oscillators & frequency helpers
• Modifiers: volume, panning, clipping, frequency processors
• Composition: Chain (serial), WaveAdder (parallel mix)
• Noise: white, pink, brownian, blue, grey, velvet, sample-and-hold, Perlin
• Filters: Butterworth utilities, biquad resonant, acid/303-style filter
• Effects: distortion, delay, reverb, compressor
• Sequencing: step sequencers, clock, accent/slide, TB-303 helpers
• Presets: PresetBuilder / PresetLibrary
• I/O (optional): AudioOutput via the audio-io extra
• MIDI (optional): adapters and synth helpers via the midi extra

Install

From PyPI:

pip install soniclab

Optional extras:

pip install "soniclab[audio-io]"   # sounddevice + numba speed path
pip install "soniclab[midi]"       # mido + python-rtmidi
pip install "soniclab[speed]"      # numba only
pip install "soniclab[examples]"   # notebooks / plotting
pip install "soniclab[full]"       # audio-io + midi + examples

From a checkout (recommended while developing):

uv sync
# or:
python -m pip install -e ".[dev]"

Notes:

• Base install is the core NumPy/SciPy engine only.
• Realtime device playback needs working system audio drivers plus audio-io.
• MIDI needs local MIDI ports/backends plus the midi extra.

Minimal example

from soniclab import SineOscillator, __version__

print(__version__)
osc = SineOscillator(frequency=440, amplitude=0.3)
samples = osc.get_samples(44100)  # 1 second @ 44.1 kHz, float32
print(samples.shape, samples.dtype)

Chain + stereo pan:

from soniclab import SineOscillator, Chain, Volume, Panner

chain = Chain(
    SineOscillator(frequency=440, amplitude=0.4),
    Volume(0.8),
    Panner(0.25),
)
stereo = chain.get_samples(2048, mode="vectorized")  # shape (2048, 2)

PolyBLEP oscillator:

from soniclab import PolyBLEPOscillator, WaveShape

osc = PolyBLEPOscillator(
    frequency=110,
    amplitude=0.5,
    wave_shape=WaveShape.SAWTOOTH_UP,
)
samples = osc.get_samples(1024, mode="vectorized")

Optional audio output:

from soniclab.audio_io import AudioOutput
# See examples/ and soniclab/audio_io for callback-based playback.

Sample generation modes

Most generators support:

For realtime or offline renderers, prefer "vectorized" (or "auto" with buffer sizes ≥ 512).

Documentation

• docs/ — getting started, API overview, recipes, stability policy
• Local preview: uv run --with mkdocs mkdocs serve
• CHANGELOG.md
• CONTRIBUTING.md
• SECURITY.md

Testing

uv run pytest tests -q
uv run ruff check soniclab tests
uv run mypy soniclab

Suggested slices (mirrors soniclab/ layout):

uv run pytest tests/core -q
uv run pytest tests/dsp -q
uv run pytest tests/generators -q
uv run pytest tests/audio_io -q
uv run pytest tests/midi_io -q
uv run pytest tests/utils -q
uv run pytest tests/presets -q
uv run pytest tests/sequencing -q
uv run pytest tests/voices -q

Project layout

soniclab/          # installable package
tests/             # pytest suite (mirrors soniclab/ packages)
examples/          # demos & notebooks (not in sdist)
docs/              # user documentation (MkDocs)
scripts/           # benchmarks & local tooling

Public API

Import the stable surface from the top-level package:

from soniclab import (
    SineOscillator,
    SquareOscillator,
    TriangleOscillator,
    SawtoothOscillator,
    PolyBLEPOscillator,
    ADSREnvelope,
    Chain,
    WaveAdder,
    Volume,
    Panner,
    Delay,
    Reverb,
)

Optional subsystems stay in subpackages so the core install stays light:

from soniclab.audio_io import AudioOutput
from soniclab.midi_io import MIDIInput  # requires midi extra

Contributing

1. Prefer uv for environments (uv sync --group dev).
2. Keep changes covered by tests under tests/.
3. Run pytest, ruff, and mypy before opening a PR.
4. Follow existing module patterns (component descriptor + registry registration).
5. See CONTRIBUTING.md for details.

Changelog

See CHANGELOG.md.

License

See LICENSE.