Merge pull request #111 from ideoforms/docs/examples

Documentation: Creating Examples

docs/library/buffer/index.md

@@ -8,6 +8,4 @@
 - **[BufferRecorder](bufferrecorder/index.md)**: Records the input to a buffer. feedback controls overdub.
 - **[FeedbackBufferReader](feedbackbufferreader/index.md)**: Counterpart to FeedbackBufferWriter.
 - **[FeedbackBufferWriter](feedbackbufferwriter/index.md)**: Counterpart to FeedbackBufferReader.
-- **[GrainSegments](grainsegments/index.md)**: GrainSegments
 - **[Granulator](granulator/index.md)**: Granulator. Generates a grain from the given buffer each time a clock signal is received, with the given duration/rate/pan parameters. The input buffer can be mono or stereo.
-- **[SegmentPlayer](segmentplayer/index.md)**: Trigger segments of a buffer at the given onset positions.

docs/library/control/mousedown/example-0.py

@@ -0,0 +1,11 @@
+from signalflow import *
+graph = AudioGraph()
+
+#-------------------------------------------------------------------------------
+# When the left mouse button is clicked, as detected by MouseDown(), an LFO is applied to the oscillator's frequency.
+#-------------------------------------------------------------------------------
+lfo = SineLFO(5, 100, 600)
+frequency = If(MouseDown(), lfo, 100)
+osc = TriangleOscillator(frequency)
+osc.play()
+graph.wait()

docs/library/control/mousedown/example-1.py

@@ -0,0 +1,13 @@
+from signalflow import *
+graph = AudioGraph()
+
+#-------------------------------------------------------------------------------
+# A simple wobbling synthesiser controlled using the mouse. When the mouse is clicked, as detected by MouseDown(), an LFO is activated and affects the oscillator's frequency. MouseX position changes the rate of the LFO. MouseY position changes the upper frequency limit, affecting pitch.
+#-------------------------------------------------------------------------------
+rate = MouseX() * 10
+upper_limit = MouseY() * 1500
+lfo = SineLFO(rate, 100, upper_limit)
+frequency = If(MouseDown(), lfo, 100)
+osc = TriangleOscillator(frequency)
+osc.play()
+graph.wait()

docs/library/control/mousex/example-0.py

@@ -0,0 +1,11 @@
+from signalflow import *
+graph = AudioGraph()
+
+#-------------------------------------------------------------------------------
+# Using the MouseX position to change the rate of an LFO, which is modulating an oscillator's frequency
+#-------------------------------------------------------------------------------
+lfo_rate = MouseX() * 10
+frequency = SineLFO(lfo_rate, 100, 600)
+osc = TriangleOscillator(frequency)
+osc.play()
+graph.wait()    

docs/library/control/mousex/example-1.py

@@ -0,0 +1,13 @@
+from signalflow import *
+graph = AudioGraph()
+
+#-------------------------------------------------------------------------------
+# A simple wobbling synthesiser controlled using the mouse. When the mouse is clicked, as detected by MouseDown(), an LFO is activated and affects the oscillator's frequency. MouseX position changes the rate of the LFO. MouseY position changes the upper frequency limit, affecting pitch.
+#-------------------------------------------------------------------------------
+rate = MouseX() * 10
+upper_limit = MouseY() * 1500
+lfo = SineLFO(rate, 100, upper_limit)
+frequency = If(MouseDown(), lfo, 100)
+osc = TriangleOscillator(frequency)
+osc.play()
+graph.wait()

docs/library/control/mousey/example-0.py

@@ -0,0 +1,10 @@
+from signalflow import *
+graph = AudioGraph()
+
+#-------------------------------------------------------------------------------
+# Using the MouseY position to change the frequency of an oscillator.
+#-------------------------------------------------------------------------------
+frequency = MouseY() * 1000
+osc = TriangleOscillator(frequency)
+osc.play()
+graph.wait()

docs/library/control/mousey/example-1.py

@@ -0,0 +1,13 @@
+from signalflow import *
+graph = AudioGraph()
+
+#-------------------------------------------------------------------------------
+# A simple wobbling synthesiser controlled using the mouse. When the mouse is clicked, as detected by MouseDown(), an LFO is activated and affects the oscillator's frequency. MouseX position changes the rate of the LFO. MouseY position changes the upper frequency limit, affecting pitch.
+#-------------------------------------------------------------------------------
+rate = MouseX() * 10
+upper_limit = MouseY() * 1500
+lfo = SineLFO(rate, 100, upper_limit)
+frequency = If(MouseDown(), lfo, 100)
+osc = TriangleOscillator(frequency)
+osc.play()
+graph.wait()

docs/library/envelope/asrenvelope/example-0.py

@@ -0,0 +1,11 @@
+from signalflow import *
+graph = AudioGraph()
+
+#-------------------------------------------------------------------------------
+# Using an ASR Envelope to shape a square wave oscillator
+#-------------------------------------------------------------------------------
+osc = SquareOscillator(500)
+envelope = ASREnvelope(0.1, 0.0, 0.5)
+output = osc * envelope
+output.play()
+graph.wait()

docs/library/envelope/envelope/index.md

@@ -6,7 +6,7 @@ description: Envelope: Generic envelope constructor, given an array of levels, t
 # Envelope
 
 ```python
-Envelope(levels=std::vector<NodeRef> ( ), times=std::vector<NodeRef> ( ), curves=std::vector<NodeRef> ( ), clock=None, loop=false)
+Envelope(levels=std : : vector <NodeRef >(), times=std : : vector <NodeRef >(), curves=std : : vector <NodeRef >(), clock=None, loop=false)
 ```
 
 Generic envelope constructor, given an array of levels, times and curves.

docs/library/envelope/line/example-0.py

@@ -0,0 +1,12 @@
+from signalflow import *
+graph = AudioGraph()
+
+#-------------------------------------------------------------------------------
+# Using a line to control the gain of an oscillator, emulating a sidechain ducking effect.
+#-------------------------------------------------------------------------------
+clock = Impulse(frequency=1.0)
+line = Line(0.0, 0.5, 0.5, False, clock)
+osc = SawOscillator(200)
+output = osc * line
+output.play()
+graph.wait()

docs/library/index.md

@@ -19,9 +19,7 @@
 - **[BufferRecorder](buffer/bufferrecorder/index.md)**: Records the input to a buffer. feedback controls overdub.
 - **[FeedbackBufferReader](buffer/feedbackbufferreader/index.md)**: Counterpart to FeedbackBufferWriter.
 - **[FeedbackBufferWriter](buffer/feedbackbufferwriter/index.md)**: Counterpart to FeedbackBufferReader.
-- **[GrainSegments](buffer/grainsegments/index.md)**: GrainSegments
 - **[Granulator](buffer/granulator/index.md)**: Granulator. Generates a grain from the given buffer each time a clock signal is received, with the given duration/rate/pan parameters. The input buffer can be mono or stereo.
-- **[SegmentPlayer](buffer/segmentplayer/index.md)**: Trigger segments of a buffer at the given onset positions.
 
 ---
 
@@ -102,8 +100,8 @@
 - **[SawOscillator](oscillators/sawoscillator/index.md)**: Produces a (non-band-limited) sawtooth wave, with the given `frequency` and `phase` offset. When a `reset` or trigger is received, resets the phase to zero.
 - **[SineLFO](oscillators/sinelfo/index.md)**: Produces a sinusoidal LFO at the given `frequency` and `phase` offset, with output ranging from `min` to `max`.
 - **[SineOscillator](oscillators/sineoscillator/index.md)**: Produces a sine wave at the given `frequency`.
-- **[SquareLFO](oscillators/squarelfo/index.md)**: Produces a pulse wave LFO with the given `frequency` and pulsewidth of `width`, ranging from `min` to `max`, where `width` of `0.5` is a square wave.
-- **[SquareOscillator](oscillators/squareoscillator/index.md)**: Produces a pulse wave with the given `frequency` and pulse `width`, where `width` of `0.5` is a square wave and other `width` values produce a rectangular wave.
+- **[SquareLFO](oscillators/squarelfo/index.md)**: Produces a pulse wave LFO with the given `frequency` and pulse `width`,  ranging from `min` to `max`, where `width` of `0.5` is a square wave and other values produce a rectangular wave.
+- **[SquareOscillator](oscillators/squareoscillator/index.md)**: Produces a pulse wave with the given `frequency` and pulse `width`,  where `width` of `0.5` is a square wave and other values produce a rectangular wave.
 - **[TriangleLFO](oscillators/trianglelfo/index.md)**: Produces a triangle LFO with the given `frequency` and `phase` offset, ranging from `min` to `max`.
 - **[TriangleOscillator](oscillators/triangleoscillator/index.md)**: Produces a triangle wave with the given `frequency`.
 - **[Wavetable](oscillators/wavetable/index.md)**: Plays the wavetable stored in buffer at the given `frequency` and `phase` offset. `sync` can be used to provide a hard sync input, which resets the wavetable's phase at each zero-crossing.
@@ -176,7 +174,6 @@
 - **[Euclidean](sequencing/euclidean/index.md)**: Euclidean rhythm as described by Toussaint, with `sequence_length` (n) and `num_events` (k), driven by `clock`.
 - **[FlipFlop](sequencing/flipflop/index.md)**: Flips from 0/1 on each `clock`.
 - **[ImpulseSequence](sequencing/impulsesequence/index.md)**: Each time a `clock` or trigger is received, outputs the next value in `sequence`. At all other times, outputs zero.
-- **[Index](sequencing/index/index.md)**: Outputs the value in `list` corresponding to `index`.
 - **[Latch](sequencing/latch/index.md)**: Initially outputs 0. When a trigger is received at `set`, outputs 1. When a trigger is subsequently received at `reset`, outputs 0, until the next `set`.
 - **[Sequence](sequencing/sequence/index.md)**: Outputs the elements in `sequence`, incrementing position on each `clock`.
 

docs/library/oscillators/impulse/example-0.py

@@ -0,0 +1,12 @@
+from signalflow import *
+graph = AudioGraph()
+
+#-------------------------------------------------------------------------------
+# Using an Impulse node as a clock to trigger an envelope once per second.
+#-------------------------------------------------------------------------------
+clock = Impulse(1.0)
+osc = TriangleOscillator(250)
+envelope = ASREnvelope(0.01, 0.0, 0.5, 1.0, clock)
+output = osc * envelope
+output.play()
+graph.wait()

docs/library/oscillators/impulse/index.md

@@ -11,3 +11,15 @@ Impulse(frequency=1.0)
 
 Produces a value of 1 at the given `frequency`, with output of 0 at all other times. If frequency is 0, produces a single impulse.
 
+### Examples
+
+```python
+
+#-------------------------------------------------------------------------------
+# Impulse generator producing an impulse every second (60bpm)
+#-------------------------------------------------------------------------------
+impulse = Impulse(frequency=1.0)
+output = impulse * 0.5
+output.play()
+```
+

docs/library/oscillators/index.md

@@ -7,8 +7,8 @@
 - **[SawOscillator](sawoscillator/index.md)**: Produces a (non-band-limited) sawtooth wave, with the given `frequency` and `phase` offset. When a `reset` or trigger is received, resets the phase to zero.
 - **[SineLFO](sinelfo/index.md)**: Produces a sinusoidal LFO at the given `frequency` and `phase` offset, with output ranging from `min` to `max`.
 - **[SineOscillator](sineoscillator/index.md)**: Produces a sine wave at the given `frequency`.
-- **[SquareLFO](squarelfo/index.md)**: Produces a pulse wave LFO with the given `frequency` and pulsewidth of `width`, ranging from `min` to `max`, where `width` of `0.5` is a square wave.
-- **[SquareOscillator](squareoscillator/index.md)**: Produces a pulse wave with the given `frequency` and pulse `width`, where `width` of `0.5` is a square wave and other `width` values produce a rectangular wave.
+- **[SquareLFO](squarelfo/index.md)**: Produces a pulse wave LFO with the given `frequency` and pulse `width`,  ranging from `min` to `max`, where `width` of `0.5` is a square wave and other values produce a rectangular wave.
+- **[SquareOscillator](squareoscillator/index.md)**: Produces a pulse wave with the given `frequency` and pulse `width`,  where `width` of `0.5` is a square wave and other values produce a rectangular wave.
 - **[TriangleLFO](trianglelfo/index.md)**: Produces a triangle LFO with the given `frequency` and `phase` offset, ranging from `min` to `max`.
 - **[TriangleOscillator](triangleoscillator/index.md)**: Produces a triangle wave with the given `frequency`.
 - **[Wavetable](wavetable/index.md)**: Plays the wavetable stored in buffer at the given `frequency` and `phase` offset. `sync` can be used to provide a hard sync input, which resets the wavetable's phase at each zero-crossing.

docs/library/oscillators/sawlfo/example-0.py

@@ -0,0 +1,10 @@
+from signalflow import *
+graph = AudioGraph()
+
+#-------------------------------------------------------------------------------
+# Siren effect, using a sawtooth LFO to modulate a sinewave's frequency
+#-------------------------------------------------------------------------------
+lfo = SawLFO(1, 200, 1000)
+sine = SineOscillator(lfo)
+sine.play()
+graph.wait()

docs/library/oscillators/sawlfo/index.md

@@ -1,13 +1,33 @@
 title: SawLFO node documentation
-description: SawLFO: Produces a sawtooth LFO, with output ranging from `min` to `max`.
+description: SawLFO: Produces a sawtooth LFO at the fiven `frequency` and `phase` offset, with output ranging from `min` to `max`.
 
-[Reference library](../../index.md) > [Oscillators](../index.md) > [SawLFO](index.md)
+[Reference library](../index.md) > [Oscillators](index.md) > [SawLFO](sawlfo.md)
 
 # SawLFO
 
 ```python
 SawLFO(frequency=1.0, min=0.0, max=1.0, phase=0.0)
 ```
 
-Produces a sawtooth LFO, with output ranging from `min` to `max`.
+Produces a sawtooth LFO at the given `frequency` and `phase` offset, with output ranging from `min` to `max`.
 
+### Examples
+
+```python
+
+<<<<<<< HEAD
+# Siren effect, using a sawtooth LFO to modulate a sine wave's frequency
+lfo = SawLFO(1, 200, 1000)
+sine = SineOscillator(lfo)
+sine.play()
+```
+=======
+#-------------------------------------------------------------------------------
+# Siren effect, using a sawtooth LFO to modulate a sinewave's frequency
+#-------------------------------------------------------------------------------
+lfo = SawLFO(1, 200, 1000)
+sine = SineOscillator(lfo)
+sine.play()
+```
+
+>>>>>>> docs/examples

docs/library/oscillators/sawoscillator/example-0.py

@@ -0,0 +1,11 @@
+from signalflow import *
+graph = AudioGraph()
+
+#-------------------------------------------------------------------------------
+# Simple saw wave oscillator shaped by an envelope
+#-------------------------------------------------------------------------------
+saw = SawOscillator(440)
+envelope = ASREnvelope(0.05, 0.1, 0.5)
+output = saw * envelope
+output.play()
+graph.wait()

docs/library/oscillators/sawoscillator/index.md

@@ -11,3 +11,16 @@ SawOscillator(frequency=440, phase=None, reset=None)
 
 Produces a (non-band-limited) sawtooth wave, with the given `frequency` and `phase` offset. When a `reset` or trigger is received, resets the phase to zero.
 
+### Examples
+
+```python
+
+#-------------------------------------------------------------------------------
+# Simple saw wave oscillator shaped by an envelope
+#-------------------------------------------------------------------------------
+saw = SawOscillator(440)
+envelope = ASREnvelope(0.05, 0.1, 0.5)
+output = saw * envelope
+output.play()
+```
+

docs/library/oscillators/sinelfo/example-0.py

@@ -1,7 +1,9 @@
 from signalflow import *
 graph = AudioGraph()
 
+#-------------------------------------------------------------------------------
 # Siren effect, using a sinewave LFO to modulate a sawtooth's frequency
+#-------------------------------------------------------------------------------
 lfo = SineLFO(1, 200, 1000)
 saw = SawOscillator(lfo)
 saw.play()

docs/library/oscillators/sinelfo/index.md

@@ -15,7 +15,9 @@ Produces a sinusoidal LFO at the given `frequency` and `phase` offset, with outp
 
 ```python
 
+#-------------------------------------------------------------------------------
 # Siren effect, using a sinewave LFO to modulate a sawtooth's frequency
+#-------------------------------------------------------------------------------
 lfo = SineLFO(1, 200, 1000)
 saw = SawOscillator(lfo)
 saw.play()

docs/library/oscillators/sineoscillator/example-0.py

@@ -0,0 +1,11 @@
+from signalflow import *
+graph = AudioGraph()
+
+#-------------------------------------------------------------------------------
+# Simple sine wave oscillator shaped by an envelope
+#-------------------------------------------------------------------------------
+sine = SineOscillator(440)
+envelope = ASREnvelope(0.1, 0.1, 0.5)
+output = sine * envelope
+output.play()
+graph.wait()

docs/library/oscillators/sineoscillator/index.md

@@ -11,3 +11,16 @@ SineOscillator(frequency=440)
 
 Produces a sine wave at the given `frequency`.
 
+### Examples
+
+```python
+
+#-------------------------------------------------------------------------------
+# Simple sine wave oscillator shaped by an envelope
+#-------------------------------------------------------------------------------
+sine = SineOscillator(440)
+envelope = ASREnvelope(0.1, 0.1, 0.5)
+output = sine * envelope
+output.play()
+```
+

docs/library/oscillators/squarelfo/example-0.py

@@ -0,0 +1,10 @@
+from signalflow import *
+graph = AudioGraph()
+
+#-------------------------------------------------------------------------------
+# Alarm effect, using a pulse wave LFO to modulate a sinewave's frequency
+#-------------------------------------------------------------------------------
+lfo = SquareLFO(1, 200, 400)
+sine = SineOscillator(lfo)
+sine.play()
+graph.wait()

docs/library/oscillators/squarelfo/index.md

@@ -1,5 +1,5 @@
 title: SquareLFO node documentation
-description: SquareLFO: Produces a pulse wave LFO with the given `frequency` and pulsewidth of `width`, ranging from `min` to `max`, where `width` of `0.5` is a square wave.
+description: SquareLFO: Produces a pulse wave LFO with the given `frequency` and pulse `width`,  ranging from `min` to `max`, where `width` of `0.5` is a square wave and other values produce a rectangular wave.
 
 [Reference library](../../index.md) > [Oscillators](../index.md) > [SquareLFO](index.md)
 
@@ -9,5 +9,17 @@ description: SquareLFO: Produces a pulse wave LFO with the given `frequency` and
 SquareLFO(frequency=1.0, min=0.0, max=1.0, width=0.5, phase=0.0)
 ```
 
-Produces a pulse wave LFO with the given `frequency` and pulsewidth of `width`, ranging from `min` to `max`, where `width` of `0.5` is a square wave.
+Produces a pulse wave LFO with the given `frequency` and pulse `width`,  ranging from `min` to `max`, where `width` of `0.5` is a square wave and other values produce a rectangular wave.
+
+### Examples
+
+```python
+
+#-------------------------------------------------------------------------------
+# Alarm effect, using a pulse wave LFO to modulate a sinewave's frequency
+#-------------------------------------------------------------------------------
+lfo = SquareLFO(1, 200, 400)
+sine = SineOscillator(lfo)
+sine.play()
+```
 

docs/library/oscillators/squareoscillator/example-0.py

@@ -0,0 +1,11 @@
+from signalflow import *
+graph = AudioGraph()
+
+#-------------------------------------------------------------------------------
+# Simple square wave oscillator shaped by an envelope
+#-------------------------------------------------------------------------------
+square = SquareOscillator(440)
+envelope = ASREnvelope(0, 0.1, 0.5)
+output = square * envelope
+output.play()
+graph.wait()