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, morphable wavetable, FM/PM helpers (simple_fm / simple_pm, named modulation lanes)
• Sample playback: SamplePlayer with pitch, loop, and poly factory
• Modulation: ADSR / decay envelopes (linear / exponential / polynomial curves), LFO (free rate or tempo-sync), modulated oscillators & frequency helpers
• Modifiers: volume, panning, clipping, mid/side width, multi-channel remix / surround panner (mono → stereo / quad / 5.1)
• Composition: Chain (serial), WaveAdder (parallel mix)
• Noise: white, pink, brownian, blue, grey, velvet, sample-and-hold, Perlin
• Filters: Butterworth, biquad resonant, acid/303, multi-mode SVF, ladder (Moog-style)
• Effects: distortion, delay, reverb, compressor, chorus, flanger, phaser, limiter, parametric EQ, bitcrusher
• Voices: SubtractiveVoice (osc → SVF → dual ADSR + LFO), TB303Voice
• Sequencing: step sequencers, arpeggiator, clock, accent/slide
• Presets: PresetBuilder / PresetLibrary
• I/O (optional): AudioOutput, AudioInput, AudioRecorder, device helpers via the audio-io extra
• MIDI (optional): input/files, mono & poly synths (velocity, sustain, bend), mono/poly MIDI→CV, clock transport, MPE, sample timelines via the midi extra

Docs: Getting started · Feature guide · Recipes · Examples catalog · Sound gallery notebook

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

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

Polyphonic MIDI synth (velocity-sensitive voices):

from soniclab import ADSREnvelope, Chain, ModulatedVolume, SineOscillator
from soniclab.midi_io import PolyphonicSynth  # requires midi extra

def voice_factory():
    osc = SineOscillator(440, amplitude=0.25)
    env = ADSREnvelope(attack_duration=0.01, release_duration=0.2)
    return Chain(osc, ModulatedVolume(env))

synth = PolyphonicSynth(voice_factory, max_voices=8)
synth.note_on(60, 100)
synth.note_on(64, 80)
samples = synth.get_samples(2048)

See examples/midi/polyphony_usage.py and docs/recipes.md.

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.

Publishing a release

Version is read from soniclab/_version.py (CalVer-style YYYY.MINOR.MICRO). Publishing uses GitHub Actions (Trusted Publisher) on a GitHub Release.

1. Prep

   • Bump major / minor / micro in soniclab/_version.py.
   • Move the matching section in CHANGELOG.md from Unreleased to a dated heading (e.g. ## [2026.1.3] - 2026-07-31).
   • Commit on main and push so CI is green (pytest, ruff, mypy, build).

2. Local sanity (optional but recommended)

   uv run pytest tests -q
   uv run ruff check soniclab tests
   uv run mypy soniclab
   uv build
   uv run --with twine twine check dist/*
   

3. Tag & release (creates the PyPI publish)

   git tag 2026.1.3
   git push origin main --tags
   # Then publish a GitHub Release for that tag (UI or gh):
   # gh release create 2026.1.3 --title "2026.1.3" --notes-file CHANGELOG.md
   

   The Publish to PyPI workflow builds the sdist/wheel and uploads to PyPI when the release is published. For a dry run, use Actions → Publish to PyPI → Run workflow with target testpypi.

4. Verify — pypi.org/project/soniclab shows the new version; pip install -U soniclab installs it.

Do not upload the same version twice to PyPI (versions are immutable).

Changelog

See CHANGELOG.md.

License

See LICENSE.