Metadata-Version: 2.4
Name: circuitpython-synthtools
Version: 0.5.1
Summary: CircuitPython helper library to do help doing synthio
Author-email: Tod Kurt <tod@todbot.com>
License: MIT
Project-URL: Homepage, https://github.com/todbot/CircuitPython_SynthTools
Keywords: adafruit,blinka,circuitpython,micropython,synthtools,synth,synthio,synthesizer,waveform,wav,wave,wavetable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: System :: Hardware
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: Adafruit-Blinka
Provides-Extra: optional
Dynamic: license-file

Introduction
============


.. image:: https://readthedocs.org/projects/circuitpython-synthtools/badge/?version=latest
    :target: https://circuitpython-synthtools.readthedocs.io/
    :alt: Documentation Status



.. image:: https://img.shields.io/discord/327254708534116352.svg
    :target: https://adafru.it/discord
    :alt: Discord


.. image:: https://github.com/todbot/CircuitPython_SynthTools/workflows/Build%20CI/badge.svg
    :target: https://github.com/todbot/CircuitPython_SynthTools/actions
    :alt: Build Status


.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
    :target: https://github.com/astral-sh/ruff
    :alt: Code Style: Ruff

CircuitPython library with tools for making synths with synthio

This library is a collection of tools derived from my many years of playing
with CircuitPython, ``synthio``, and building synthesizers in general.
Concepts pulled from these projects and others:

- `CircuitPython Synthio Tutorial <https://todbot.github.io/CircuitPython_Synthio_Tutorial/>`_
- `circuitpython synthio tricks <https://github.com/todbot/circuitpython-synthio-tricks>`_
- `pico_test_synth <https://github.com/todbot/pico_test_synth>`_
- `picotouch_synth <https://github.com/todbot/picotouch_synth>`_
- `picostepseq <https://github.com/todbot/picostepseq>`_

Dependencies
=============
This driver depends on:

* `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_

Please ensure all dependencies are available on the CircuitPython filesystem.
This is easily achieved by downloading
`the Adafruit library and driver bundle <https://circuitpython.org/libraries>`_
or individual libraries can be installed using
`circup <https://github.com/adafruit/circup>`_.


Installing to a Connected CircuitPython Device with Circup
==========================================================

Make sure that you have ``circup`` installed in your Python environment.
Install it with the following command if necessary:

.. code-block:: shell

    pip3 install circup

With ``circup`` installed and your CircuitPython device connected use the
following command to install:

.. code-block:: shell

    circup install synthtools

Or the following command to update an existing version:

.. code-block:: shell

    circup update

Usage Example
=============

.. code-block:: python

    import time
    from synth_setup import synth as engine
    from synthtools import Patch, SubtractiveSynth

    patch1 = Patch(name="fat bass", wave="ASAW", detune=1.004,
                   filt_type="LPF", filt_f=800, filt_q=1.4,
                   amp_env=[0.01, 0.1, 0.8, 0.4],
                   vib_rate=5.5, vib_depth=0.0,
                   # AHR filter envelope: cutoff swings 800 -> 3800 Hz and back
                   fenv_amount=3000, fenv_attack=0.02, fenv_release=0.30,
                   # a slow cyclic wobble on top of it (0 = off)
                   filt_lfo_rate=0.4, filt_lfo_amount=0.3)
    synth = SubtractiveSynth(engine, patch1)
    arp = (36, 39, 43, 48)
    i = 0
    sweep = 0
    while True:
        synth.note_on(arp[i % len(arp)], velocity=110)
        time.sleep(0.11)
        synth.note_off(arp[i % len(arp)])
        time.sleep(0.02)
        i += 1
        if i % 32 == 0:  # flip waveforms now and then
            synth.wave = "ASQU" if synth.wave == "ASAW" else "ASAW"


What's Included
===============

* ``Synth`` -- synth engine base: shared voice, patch, and modulation handling,
  with ``mono`` mode for a single-voice synth with ``glide_time``  portamento
* ``SubtractiveSynth`` -- subtractive two-oscillator synth w/ detune
* ``WavetableSynth`` -- wavetable-playback with adjustable wave_pos
* ``BasslineSynth`` -- TB-303-style acid bassline: monophonic, one
  oscillator, a decay-only filter sweep, per-step slide and accent. Can
  own its own filter/distortion/echo effects chain via ``fx_*`` patch
  fields
* ``EffectsChain`` -- a generic post-synth effects chain: add, insert, or
  remove any ``audiofilters``/``audiodelays`` effect and it stays wired.
  ``tracking_filter()`` builds extra filter stages that follow the synth's
  own cutoff and resonance for a steeper slope (needs ``audiofilters`` in
  the build)
* ``Patch`` -- inert, JSON-able patch data; save/load with
  ``save_patches()`` / ``load_patches()``
* ``Wavetable`` -- loads a wavetable WAV file and lerps between frames
* ``AHREnvelope`` -- shared-block attack/release envelope, used for both
  the filter and pitch envelopes
* ``Waves`` -- waveform factory (saw, square, sine, triangle, noise, and
  "analog" variants)
* ``Arpeggiator`` / ``StepSequencer`` / ``TrigSequencer`` -- poll-based
  sequencers with on/off callbacks
* ``Param`` / ``ParamSet`` -- knob-pickup and scaling for UIs with fewer
  knobs than parameters
* ``Glider`` -- a standalone pitch-slide block for hand-built
  ``synthio.Note`` graphs (the engines above have their own portamento,
  via ``mono`` + ``glide_time``)
* ``RollingAverage`` -- moving-average smoothing for noisy knob reads

Documentation
=============
API documentation for this library can be found on `Read the Docs <https://circuitpython-synthtools.readthedocs.io/>`_.

For information on building library documentation, please check out
`this guide <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/sharing-our-docs-on-readthedocs#sphinx-5-1>`_.

Contributing
============

Contributions are welcome! Please read our `Code of Conduct
<https://github.com/todbot/CircuitPython_SynthTools/blob/HEAD/CODE_OF_CONDUCT.md>`_
before contributing to help this project stay welcoming.
