Update docs with new examples

docs/library/envelope/asrenvelope/index.md

@@ -25,3 +25,32 @@ output.play()
 
 ```
 
+```python
+
+#-------------------------------------------------------------------------------
+# Using ASREnvelope to shape the sound of an oscillator over time.
+# The Line node generates a continuously-changing value which we use as the 
+# release time.
+#-------------------------------------------------------------------------------
+clock = Impulse(8.0)
+CMaj7 = [ 60, 64, 67, 71, 74, 76 ] * 8
+FMaj9 = [ 65, 69, 72, 76, 77, 81 ] * 8
+arpeggios = CMaj7 + FMaj9
+sequence = Sequence(arpeggios, clock)
+frequency = MidiNoteToFrequency(sequence)
+
+oscillator = TriangleOscillator(frequency)
+release = Line(0.1, 0.5, 6, True)
+envelope = ASREnvelope(attack=0.0, 
+                       sustain=0.0, 
+                       release=release, 
+                       curve=1.0, 
+                       clock=clock)
+voice = oscillator * envelope
+
+pan = SineLFO(0.1667, -1.0, 1.0)
+output = StereoPanner(voice, pan)
+output.play()
+
+```
+

docs/library/envelope/index.md

@@ -6,5 +6,5 @@
 - **[ASREnvelope](asrenvelope/index.md)**: Attack-sustain-release envelope.
 - **[DetectSilence](detectsilence/index.md)**: Detects blocks of silence below the threshold value. Used as an auto-free node to terminate a Patch after processing is complete.
 - **[Envelope](envelope/index.md)**: Generic envelope constructor, given an array of levels, times and curves.
-- **[Line](line/index.md)**: Line segment with the given start/end values and duration. If loop is true, repeats indefinitely. Retriggers on a clock signal.
+- **[Line](line/index.md)**: Line segment with the given start/end values, and duration (in seconds). If loop is true, repeats indefinitely. Retriggers on a clock signal.
 - **[RectangularEnvelope](rectangularenvelope/index.md)**: Rectangular envelope with the given sustain duration.

docs/library/envelope/line/index.md

@@ -1,5 +1,5 @@
 title: Line node documentation
-description: Line: Line segment with the given start/end values and duration. If loop is true, repeats indefinitely. Retriggers on a clock signal.
+description: Line: Line segment with the given start/end values, and duration (in seconds). If loop is true, repeats indefinitely. Retriggers on a clock signal.
 
 [Reference library](../../index.md) > [Envelope](../index.md) > [Line](index.md)
 
@@ -9,7 +9,7 @@ description: Line: Line segment with the given start/end values and duration. If
 Line(start=0.0, end=1.0, time=1.0, loop=0, clock=None)
 ```
 
-Line segment with the given start/end values and duration. If loop is true, repeats indefinitely. Retriggers on a clock signal.
+Line segment with the given start/end values, and duration (in seconds). If loop is true, repeats indefinitely. Retriggers on a clock signal.
 
 ### Examples
 
@@ -22,7 +22,31 @@ Line segment with the given start/end values and duration. If loop is true, repe
 clock = Impulse(frequency=1.0)
 line = Line(0.0, 0.5, 0.5, False, clock)
 osc = SawOscillator(200)
-output = osc * line
+output = StereoPanner(osc * line)
+output.play()
+
+```
+
+```python
+
+#-------------------------------------------------------------------------------
+# Using Line to repeatedly alter the release value of an envelope applied to the
+# main synth voice, in time with the music.
+#-------------------------------------------------------------------------------
+clock = Impulse(8.0)
+CMaj7 = [ 60, 64, 67, 71, 74, 76 ] * 8
+FMaj9 = [ 65, 69, 72, 76, 77, 81 ] * 8
+arpeggios = CMaj7 + FMaj9
+sequence = Sequence(arpeggios, clock)
+frequency = MidiNoteToFrequency(sequence)
+
+oscillator = TriangleOscillator(frequency)
+release = Line(0.1, 0.5, 6, True)
+envelope = ASREnvelope(0.0, 0.0, release, 1.0, clock)
+voice = oscillator * envelope
+
+pan = SineLFO(0.1667, -1.0, 1.0)
+output = StereoPanner(voice, pan)
 output.play()
 
 ```

docs/library/fft/index.md

@@ -6,6 +6,8 @@
 - **[FFTConvolve](fftconvolve/index.md)**: Frequency-domain convolution, using overlap-add. Useful for convolution reverb, with the input buffer containing an impulse response. Requires an FFT* input.
 - **[FFTContrast](fftcontrast/index.md)**: FFT Contrast. Requires an FFT* input.
 - **[FFTFlipSpectrum](fftflipspectrum/index.md)**: Flips the FFT magnitude spectrum in the X axis. Requires an FFT* input.
+- **[FFTMagnitudePhaseArray](fftmagnitudephasearray/index.md)**: Fixed mag/phase array.
+- **[FFTRandomPhase](fftrandomphase/index.md)**: Randomise phase values.
 - **[FFT](fft/index.md)**: Fast Fourier Transform. Takes a time-domain input, and generates a frequency-domain (FFT) output.
 - **[FFTFindPeaks](fftfindpeaks/index.md)**: Find peaks in the FFT magnitude spectrum. Requires an FFT* input.
 - **[IFFT](ifft/index.md)**: Inverse Fast Fourier Transform. Requires an FFT* input, generates a time-domain output.

docs/library/index.md

@@ -45,7 +45,7 @@
 - **[ASREnvelope](envelope/asrenvelope/index.md)**: Attack-sustain-release envelope.
 - **[DetectSilence](envelope/detectsilence/index.md)**: Detects blocks of silence below the threshold value. Used as an auto-free node to terminate a Patch after processing is complete.
 - **[Envelope](envelope/envelope/index.md)**: Generic envelope constructor, given an array of levels, times and curves.
-- **[Line](envelope/line/index.md)**: Line segment with the given start/end values and duration. If loop is true, repeats indefinitely. Retriggers on a clock signal.
+- **[Line](envelope/line/index.md)**: Line segment with the given start/end values, and duration (in seconds). If loop is true, repeats indefinitely. Retriggers on a clock signal.
 - **[RectangularEnvelope](envelope/rectangularenvelope/index.md)**: Rectangular envelope with the given sustain duration.
 
 ---
@@ -56,6 +56,8 @@
 - **[FFTConvolve](fft/fftconvolve/index.md)**: Frequency-domain convolution, using overlap-add. Useful for convolution reverb, with the input buffer containing an impulse response. Requires an FFT* input.
 - **[FFTContrast](fft/fftcontrast/index.md)**: FFT Contrast. Requires an FFT* input.
 - **[FFTFlipSpectrum](fft/fftflipspectrum/index.md)**: Flips the FFT magnitude spectrum in the X axis. Requires an FFT* input.
+- **[FFTMagnitudePhaseArray](fft/fftmagnitudephasearray/index.md)**: Fixed mag/phase array.
+- **[FFTRandomPhase](fft/fftrandomphase/index.md)**: Randomise phase values.
 - **[FFT](fft/fft/index.md)**: Fast Fourier Transform. Takes a time-domain input, and generates a frequency-domain (FFT) output.
 - **[FFTFindPeaks](fft/fftfindpeaks/index.md)**: Find peaks in the FFT magnitude spectrum. Requires an FFT* input.
 - **[IFFT](fft/ifft/index.md)**: Inverse Fast Fourier Transform. Requires an FFT* input, generates a time-domain output.
@@ -96,6 +98,7 @@
 - **[ScaleLinLin](operators/scalelinlin/index.md)**: Scales the input from a linear range (between a and b) to a linear range (between c and d).
 - **[Subtract](operators/subtract/index.md)**: Subtract each sample of b from each sample of a. Can also be written as a - b
 - **[Sum](operators/sum/index.md)**: Sums the output of all of the input nodes, by sample.
+- **[TimeShift](operators/timeshift/index.md)**: TimeShift
 - **[Sin](operators/sin/index.md)**: Outputs sin(a), per sample.
 - **[Cos](operators/cos/index.md)**: Outputs cos(a), per sample.
 - **[Tan](operators/tan/index.md)**: Outputs tan(a), per sample.

docs/library/operators/channelarray/index.md

@@ -11,3 +11,17 @@ ChannelArray()
 
 Takes an array of inputs and spreads them across multiple channels of output.
 
+### Examples
+
+```python
+
+#-------------------------------------------------------------------------------
+# Using ChannelArray to pan a low tone to the left and a high tone to the right.
+#-------------------------------------------------------------------------------
+low = TriangleOscillator(220)
+high = TriangleOscillator(660)
+panned = ChannelArray([low, high]) * 0.3
+panned.play()
+
+```
+

docs/library/operators/index.md

@@ -29,6 +29,7 @@
 - **[ScaleLinLin](scalelinlin/index.md)**: Scales the input from a linear range (between a and b) to a linear range (between c and d).
 - **[Subtract](subtract/index.md)**: Subtract each sample of b from each sample of a. Can also be written as a - b
 - **[Sum](sum/index.md)**: Sums the output of all of the input nodes, by sample.
+- **[TimeShift](timeshift/index.md)**: TimeShift
 - **[Sin](sin/index.md)**: Outputs sin(a), per sample.
 - **[Cos](cos/index.md)**: Outputs cos(a), per sample.
 - **[Tan](tan/index.md)**: Outputs tan(a), per sample.

docs/library/oscillators/impulse/index.md

@@ -21,7 +21,7 @@ Produces a value of 1 at the given `frequency`, with output of 0 at all other ti
 clock = Impulse(1.0)
 osc = TriangleOscillator(250)
 envelope = ASREnvelope(0.01, 0.0, 0.5, 1.0, clock)
-output = osc * envelope
+output = StereoPanner(osc * envelope)
 output.play()
 
 ```

docs/library/oscillators/sawlfo/index.md

@@ -20,7 +20,8 @@ Produces a sawtooth LFO at the given `frequency` and `phase` offset, with output
 #-------------------------------------------------------------------------------
 lfo = SawLFO(1, 200, 1000)
 sine = SineOscillator(lfo)
-sine.play()
+output = StereoPanner(sine) * 0.5
+output.play()
 
 ```
 

docs/library/oscillators/sawoscillator/index.md

@@ -20,7 +20,7 @@ Produces a (non-band-limited) sawtooth wave, with the given `frequency` and `pha
 #-------------------------------------------------------------------------------
 saw = SawOscillator(440)
 envelope = ASREnvelope(0.05, 0.1, 0.5)
-output = saw * envelope
+output = StereoPanner(saw * envelope) * 0.5
 output.play()
 
 ```

docs/library/oscillators/sinelfo/index.md

@@ -20,7 +20,8 @@ Produces a sinusoidal LFO at the given `frequency` and `phase` offset, with outp
 #-------------------------------------------------------------------------------
 lfo = SineLFO(1, 200, 1000)
 saw = SawOscillator(lfo)
-saw.play()
+output = StereoPanner(saw) * 0.3
+output.play()
 
 ```
 

docs/library/oscillators/sineoscillator/index.md

@@ -20,7 +20,7 @@ Produces a sine wave at the given `frequency`.
 #-------------------------------------------------------------------------------
 sine = SineOscillator(440)
 envelope = ASREnvelope(0.1, 0.1, 0.5)
-output = sine * envelope
+output = StereoPanner(sine * envelope) * 0.5
 output.play()
 
 ```

docs/library/oscillators/squarelfo/index.md

@@ -20,7 +20,8 @@ Produces a pulse wave LFO with the given `frequency` and pulse `width`,  ranging
 #-------------------------------------------------------------------------------
 lfo = SquareLFO(1, 200, 400)
 sine = SineOscillator(lfo)
-sine.play()
+output = StereoPanner(sine) * 0.5
+output.play()
 
 ```
 

docs/library/oscillators/squareoscillator/index.md

@@ -20,7 +20,7 @@ Produces a pulse wave with the given `frequency` and pulse `width`,  where `widt
 #-------------------------------------------------------------------------------
 square = SquareOscillator(440)
 envelope = ASREnvelope(0, 0.1, 0.5)
-output = square * envelope
+output = StereoPanner(square * envelope) * 0.5
 output.play()
 
 ```

docs/library/oscillators/trianglelfo/index.md

@@ -20,7 +20,8 @@ Produces a triangle LFO with the given `frequency` and `phase` offset, ranging f
 #-----------------------------------------------------------------------------------
 lfo = TriangleLFO(3, 200, 900)
 sine = SineOscillator(lfo)
-sine.play()
+output = StereoPanner(sine) * 0.5
+output.play()
 
 ```
 

docs/library/oscillators/triangleoscillator/index.md

@@ -20,7 +20,7 @@ Produces a triangle wave with the given `frequency`.
 #-------------------------------------------------------------------------------
 tri = TriangleOscillator(440)
 envelope = ASREnvelope(0.1, 0.1, 0.5)
-output = tri * envelope
+output = StereoPanner(tri * envelope) * 0.5
 output.play()
 
 ```

docs/library/processors/delays/allpassdelay/index.md

@@ -11,3 +11,54 @@ AllpassDelay(input=0.0, delay_time=0.1, feedback=0.5, max_delay_time=0.5)
 
 All-pass delay, with `feedback` between 0 and 1. `delay_time` must be less than or equal to `max_delay_time`.
 
+### Examples
+
+```python
+
+#-------------------------------------------------------------------------------
+# Using AllpassDelay to add a delay effect to a simple melodic sequence.
+# The original oscillator can be heard in the left channel.
+# The delay effect can be heard in the right channel.
+#-------------------------------------------------------------------------------
+clock = Impulse(1.0)
+sequence = Sequence([ 60, 62, 64, 65, 67, 69, 71, 72 ], clock)
+frequency = MidiNoteToFrequency(sequence)
+
+oscillator = TriangleOscillator(frequency)
+envelope = ASREnvelope(0, 0.2, 0.3, 1.0, clock)
+voice = oscillator * envelope
+delayed = AllpassDelay(input=voice, 
+                       delay_time=0.4, 
+                       feedback=0.8)
+
+output = ChannelArray([ voice, delayed ]) * 0.75
+output.play()
+
+```
+
+```python
+
+#-------------------------------------------------------------------------------
+# Using AllpassDelay to add a dreamy atmosphere to synth arpeggios
+#-------------------------------------------------------------------------------
+clock = Impulse(3.5)
+Am7 = [ 67, 64, 60, 57 ] * 4
+D7 = [ 62, 66, 69, 72] * 4
+arpeggios = Am7 + D7
+sequence = Sequence(arpeggios, clock)
+frequency = MidiNoteToFrequency(sequence)
+
+oscillator = SquareOscillator(frequency)
+envelope = ASREnvelope(0.1, 0, 0.2, 1.0, clock)
+voice = oscillator * envelope
+filtered = SVFilter(voice, "low_pass", 4000, 0.3)
+delayed = AllpassDelay(input=filtered, 
+                       delay_time=0.15, 
+                       feedback=0.8)
+
+pan = TriangleLFO(0.1, -1.0, 1.0)
+output = StereoPanner(delayed, pan) * 0.5
+output.play()
+
+```
+

docs/library/processors/delays/combdelay/index.md

@@ -11,3 +11,29 @@ CombDelay(input=0.0, delay_time=0.1, feedback=0.5, max_delay_time=0.5)
 
 Comb delay, with `feedback` between 0 and 1. `delay_time` must be less than or equal to `max_delay_time`.
 
+### Examples
+
+```python
+
+#-------------------------------------------------------------------------------
+# Using CombDelay to change the character of a saw wave oscillator.
+#-------------------------------------------------------------------------------
+clock = Impulse(4)
+arpeggio = [60, 62, 64, 66, 68, 70,
+            72, 70, 68, 66, 64, 62]
+sequence = Sequence(arpeggio, clock)
+frequency = MidiNoteToFrequency(sequence)
+
+oscillator = SawOscillator(frequency)
+envelope = ASREnvelope(0.1, 0, 0.2, 1.0, clock)
+voice = oscillator * envelope
+comb = CombDelay(input=voice, 
+                 delay_time=0.09, 
+                 feedback=0.6, 
+                 max_delay_time=0.9)
+
+output = StereoPanner(comb) * 0.5
+output.play()
+
+```
+

docs/library/processors/delays/onetapdelay/index.md

@@ -11,3 +11,49 @@ OneTapDelay(input=0.0, delay_time=0.1, max_delay_time=0.5)
 
 Single-tap delay line. `delay_time` must be less than or equal to `max_delay_time`.
 
+### Examples
+
+```python
+
+#-------------------------------------------------------------------------------
+# Using OneTapDelay to create a delay effect with no feedback.
+# The original sound is heard in the left channel, and the delayed sound in the
+# right channel.
+#-------------------------------------------------------------------------------
+clock = Impulse(1)
+oscillator = TriangleOscillator(440)
+envelope = ASREnvelope(0.001, 0, 0.3, 1.0, clock)
+voice = oscillator * envelope
+delayed = OneTapDelay(voice, 0.25) * 0.5
+output = ChannelArray([voice, delayed]) * 0.5
+output.play()
+
+```
+
+```python
+
+#-------------------------------------------------------------------------------
+# Using OneTapDelay to bring controlled rhythmic interest to a melodic sequence
+#-------------------------------------------------------------------------------
+clock = Impulse(3.5)
+Dm = [ 62, 65, 69 ] * 2
+Bdim = [ 59, 62, 65 ] * 2
+Gm = [55, 58, 62 ] * 2
+Bb = [77, 74, 70 ]
+A = [ 76, 73, 69 ]
+
+arpeggios = Dm + Bdim + Gm + Bb + A
+sequence = Sequence(arpeggios, clock)
+frequency = MidiNoteToFrequency(sequence)
+
+oscillator = SquareOscillator(frequency)
+envelope = ASREnvelope(0.1, 0, 0.2, 1.0, clock)
+voice = oscillator * envelope
+filtered = SVFilter(voice, "low_pass", 4000, 0.3)
+delayed = filtered + OneTapDelay(filtered, 0.4) * 0.5
+
+output = StereoPanner(delayed) * 0.3
+output.play()
+
+```
+

docs/library/processors/distortion/resample/index.md

@@ -11,3 +11,17 @@ Resample(input=0, sample_rate=44100, bit_rate=16)
 
 Resampler and bit crusher. `sample_rate` is in Hz, `bit_rate` is an integer between 0 and 16.
 
+### Examples
+
+```python
+
+#-------------------------------------------------------------------------------
+# Using Resample to distort a sine wave.
+#-------------------------------------------------------------------------------
+sine = SineOscillator(440)
+crushed = Resample(sine, 11025, 4)
+output = StereoPanner(crushed) * 0.3
+output.play()
+
+```
+