synthio: Add LFOs

[jepler]

This switches from hard coded tremolo/vibrato, to allowing much more control via nestable LFOs.

The new LFO object's API is like so:

BlockInput = Union['LFO', float]

class LFO:
    """A low-frequency oscillator

    Every `rate` seconds, the output of the LFO cycles through its `waveform`.
    The output at any particular moment is ``waveform[idx] * scale + offset``.

    `rate`, `offset`, `scale`, and `once` can be changed at run-time.

    An LFO only updates if it is actually associated with a playing Note,
    including if it is indirectly associated with the Note via an intermediate
    LFO.

    Using the same LFO as an input to multiple other LFOs or Notes is OK, but
    the result if an LFO is tied to multiple Synthtesizer objects is undefined."""

    def __init__(
        self,
        waveform: ReadableBuffer,
        *,
        rate: BlockInput = 1.0,
        scale: BlockInput = 1.0,
        offset: BlockInput = 0,
        once=False,
    ):
        pass
    waveform: Optional[ReadableBuffer]
    """The waveform of this lfo. (read-only, but the values in the buffer may be modified dynamically)"""
    rate: BlockInput
    """The rate (in Hz) at which the LFO cycles through its waveform"""
    offset: BlockInput
    """An additive value applied to the LFO's output"""
    scale: BlockInput
    """An additive value applied to the LFO's output"""

    once: bool
    """True if the waveform should stop when it reaches its last output value, false if it should re-start at the beginning of its waveform"""

    phase: float
    """The phase of the oscillator, in the range 0 to 1 (read-only)"""

    value: float
    """The value of the oscillator (read-only)"""

    def retrigger():
        """Reset the LFO's internal index to the start of the waveform. Most useful when it its `once` property is `True`."""

A Note object now has several properties that are LFOs, replacing the earlier "depth" and "rate" properties: bend, amplitude, and ring_bend.

LFOs can refer to other LFOs and most things can be re-assigned dynamically, so for instance this program starts with a simple tone, then modulates the amplitude with a first LFO, and then modulates the rate of the first LFO with a second LFO:

n = Note(440, amplitude=.3, waveform=sine)
s.release_all()
input()

s.press((n,))
input()

n.amplitude = synthio.LFO(offset=.3, scale=.2, rate=1, waveform=sine)
input()

n.amplitude.rate = synthio.LFO(scale=4, rate=.25, waveform=sweep_in)          
input()

s.release_all()

The file doesn't seem to be embeddable here but I put a demo up in mp3 format: https://emergent.unpythonic.net/files/sandbox/lfo_test.mp3

Other API changes:

• Synthesizer methods that took a sequence of notes-or-integers can also now take a single note or integer
• The release_then_press API becomes change and adds an optional list of LFOs to retrigger. It's now documented that this is intended to be atomic with respect to sound generation, though this is only true if the iterable arguments are actually tuples or lists.

todo:

• allow a way to re-trigger multiple LFOs during the same instant of audio synthesis
• allow a way to make LFOs free running, so that they keep being updated even if not associated to a playing note
• finish updating the Note docs
• Allow midi note 0 (Closes synthio.midi_to_hz() range should be 0-127 not 1-127 #7999)

[todbot]

So far in my testing LFOs are great and work well.
One minor addition would be to have phase be in the LFO constructor so we can have multiple LFOs sharing the same waveform but being out-of-phase.

[jepler]

I added phase_offset to LFOs, I think it accomplishes that request.

[gamblor21]

Just a couple documentation comments. The rest looked good to me. Just commenting now pending all the test fixes I know you are aware of.

[tannewt]

One minor thing from me. Good otherwise!

[jepler]

Thanks for the review comments, I think I got 'em all.

[dhalbert]

1/12 is 0.0833

[dhalbert]

A couple of board builds are just stalled for CI reasons. No reason to think they would not complete. I will merge.