Finalize templates implementation and documentation

Woyten · Dec 5, 2022 · 50aba16 · 50aba16
1 parent 8e321c2
commit 50aba16
Show file tree

Hide file tree

Showing 9 changed files with 311 additions and 160 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -87,6 +87,7 @@
         "surjective",
         "sysex",
         "tenney",
+        "themself",
         "tielesch",
         "touchpad",
         "ungroup",

diff --git a/microwave/README.md b/microwave/README.md
@@ -16,6 +16,8 @@ Make xenharmonic music and explore musical tunings.
 
 It features a virtual piano UI enabling you to play polyphonic microtonal melodies with your touch screen, computer keyboard, MIDI keyboard or mouse. The UI provides information about pitches and just intervals in custom tuning systems.
 
+The built-in modular synthesis engine does not use any fixed architecture and can be customized to react to all sorts of input events.
+
 # Demo
 
 - [Xênerie (15-EDO)](https://youtu.be/0PczKDrOdUA)
@@ -64,22 +66,24 @@ This should spawn a window displaying a virtual keyboard. Use your touch screen,
 
 ![](https://github.com/Woyten/tune/raw/master/microwave/screenshot.png)
 
-## MIDI In/Out
+## MIDI In
 
-To enable playback via an external MIDI device you need to specify the name of the output device and a tuning method. The available tuning methods are `full`, `full-rt`, `octave-1`, `octave-1-rt`, `octave-2`, `octave-2-rt`, `fine-tuning` and `pitch-bend`.
+To listen for events originating from an external MIDI device you need to specify the name of the input device:
 
 ```bash
 microwave devices # List MIDI devices
-microwave run --midi-out name-of-my-device --tun-method octave-1
-microwave run --midi-in "name of my device" --tun-method octave-1 # If the device name contains spaces
+microwave run --midi-in name-of-my-device
+microwave run --midi-in "name of my device" # If the device name contains spaces
 ```
 
-To listen for events coming from a external MIDI device you only need to specify the name of the input device:
+## MIDI Out
+
+To enable playback through an external MIDI device you need to specify the name of the output device *and* a tuning method. The available tuning methods are `full`, `full-rt`, `octave-1`, `octave-1-rt`, `octave-2`, `octave-2-rt`, `fine-tuning` and `pitch-bend`.
 
 ```bash
 microwave devices # List MIDI devices
-microwave run --midi-in name-of-my-device
-microwave run --midi-in "name of my device" # If the device name contains spaces
+microwave run --midi-out name-of-my-device --tun-method octave-1
+microwave run --midi-in "name of my device" --tun-method octave-1 # If the device name contains spaces
 ```
 
 ## Soundfont Files
@@ -104,11 +108,126 @@ microwave run help
 
 On startup, `microwave` tries to locate a config file specified by the `--cfg-loc` parameter or the `MICROWAVE_CFG_LOC` environment variable. If no such file is found `microwave` will create a default config file with predefined waveforms and effects for you.
 
-### `waveforms` section
+### LF Sources
+
+Almost all waveform and effect parameters are real numbers that can update in real-time. To keep the waveforms engine performant updates are usually evaluated at a much lower rate than the audio sampling rate. LF sources, therefore, add control and expressiveness to your playing but aren't well suited for spectral modulation.
+
+To define LF sources the following data types can be used:
+
+- Numbers, e.g.
+  ```yml
+  frequency: 440.0
+  ```
+- Strings referring to a named template, e.g.
+  ```yml
+  frequency: WaveformPitch
+  ```
+- Nested LF source expressions, e.g.
+  ```yml
+  frequency: { Mul: [ 2.0, WaveformPitch ] }
+  ```
+  or (using indented style)
+  ```yml
+  frequency:
+    Mul:
+      - 2.0
+      - WaveformPitch
+  ```
+
+Unfortunately, no detailed LF source documentation is available yet. However, the example config, `microwave`'s error messages and basic YAML knowledge should enable you to find valid LF source expressions.
 
-The `waveforms` section of the config file defines waveform render stages to be applied sequentially when a key is pressed.
+### `waveform_templates` Section
 
-You can combine those stages to create the tailored sound you wish for. The following example config defines a clavinettish sounding waveform that I discovered by accident:
+The purpose of the `waveform_templates` section of the config file is to define the most important LF sources s.t. they do not have to be redefined over and over again.
+
+#### Example: Using Pitch-Bend Events
+
+Looking at the initially created config file the following template definition can be found:
+
+```yml
+waveform_templates:
+  - name: WaveformPitch
+    value:
+      Mul:
+        - Property:
+            kind: WaveformPitch
+        - Semitones:
+            Controller:
+              kind: PitchBend
+              map0: 0.0
+              map1: 2.0
+```
+
+The given fragment defines a template with name `WaveformPitch` which provides values by reading the waveform's `WaveformPitch` property and multiplying it with the pitch-bend wheel's value in whole tones.
+
+This means reacting to pitch-bend events is not a hardcoded feature of `microwave` but a behavior that the user can define by themself!
+
+#### Example: Using the Damper Pedal
+
+A second important template from the initial config file is the following one:
+
+```yml
+waveform_templates:
+  - name: Fadeout
+    value:
+      Controller:
+        kind: Damper
+        map0:
+          Property:
+            kind: OffVelocitySet
+        map1: 0.0
+```
+
+The given template provides a value describing to what extent a waveform is supposed to be faded out. It works in the following way:
+
+While a key is pressed down, `OffVelocitySet ` resolves to 0.0. As a result, `Controller`, as well, resolves to 0.0, regardless of the damper pedal state. Therefore, the waveform remains stable.
+
+As soon as a key is released, `OffVelocitySet` will resolve to 1.0. Now, `Controller` will interpolate between 0.0 (damper pedal pressed) and 1.0 (damper pedal released). Ergo, the waveform will fade out unless the damper pedal is pressed.
+
+Like in the example before, reacting to the damper pedal is not a hardcoded feature built into `microwave` but customizable behavior.
+
+#### How to Access Templates
+
+Just provide the name of the template as a single string argument. Examples:
+
+```yml
+frequency: WaveformPitch
+```
+
+```yml
+fadeout: Fadeout
+```
+
+### `waveform_envelopes` Section
+
+Every waveform needs to refer to an envelope defined in the `waveform_envelopes` section of the config file. Envelopes transfer the result of the waveform's `AudioOut` buffer to the main audio pipeline and limit the waveform's lifetime.
+
+An envelope definition typically looks like the following:
+
+```yml
+waveform_envelopes:
+  - name: Piano
+    amplitude: Velocity
+    fadeout: Fadeout
+    attack_time: 0.01
+    decay_rate: 1.0
+    release_time: 0.25
+```
+
+with
+
+- `name`: The name of the envelope.
+- `amplitude`: The amplitude factor to apply to the `AudioOut` buffer. It makes sense to use `Velocity` as a value but the user can choose whatever LF source expression they find useful.
+- `fadeout`: Defines the amount by which the waveform should fade out. **Important:** If this value is set to constant 0.0 the waveform will never fade out and continue to consume CPU resources, eventually leading to an overload of the audio thread.
+- `attack_time`: The linear attack time in seconds.
+- `decay_rate`: The exponential decay rate in 1/seconds (inverse half-life) after the attack phase is over.
+- `release_time`: The linear release time in seconds. The waveform is considered exhausted as soon as the integral over `fadeout / release_time * dt` reaches 1.0.
+
+### `waveforms` Section
+
+The `waveforms` section of the config file defines the waveform render stages to be applied sequentially when a waveform is triggered.
+
+You can mix and match as many stages as you want to create the tailored sound you wish for. The following example config defines a clavinettish sounding waveform that I discovered by accident:
 
 ```yml
 waveforms:
@@ -152,7 +271,11 @@ While rendering the sound three stages are applied:
 
 To create your own waveforms use the default config file as a starting point and try editing it by trial-and-error. Let `microwave`'s error messages guide you to find valid configurations.
 
-### `effects` section
+### `effect_templates` Section
+
+This section is completely analogous to the `waveform_templates` section but it is dedicated to work in combination with the following `effects` section.
+
+### `effects` Section
 
 The `effects` section of the config file defines the effects to be applied sequentially after the waveforms have been rendered.
 
@@ -165,25 +288,25 @@ effects:
       gain:
         Controller:
           kind: Sound9
-          from: 0.0
-          to: 0.5
+          map0: 0.0
+          map1: 0.5
       rotation_radius: 20.0
       speed:
         Controller:
           kind: Sound10
-          from: 1.0
-          to: 7.0
-      acceleration: 7.0
-      deceleration: 14.0
+          map0: 1.0
+          map1: 7.0
+      acceleration: 6.0
+      deceleration: 12.0
 ```
 
 The given config defines the following properties:
 
-- A fixed delay buffer size of 100000 samples
-- An input gain ranging from 0.0 to 0.5. The input gain can be controlled via the F9 key or MIDI CCN 78.
-- A rotation radius of 20 cm
-- A target rotation speed ranging from 1 Hz to 7 Hz. The speed can be controlled via the F10 key or MIDI CCN 79.
-- The speaker accelerates (decelerates) at 7 (14) Hz/s.
+- `buffer_size`: A fixed delay buffer size of 100000 samples
+- `gain`: An input gain ranging from 0.0 to 0.5. The input gain can be controlled via the F9 key or MIDI CCN 78.
+- `rotation_radius`: A rotation radius of 20 cm
+- `speed`: A target rotation speed ranging from 1 Hz to 7 Hz. The speed can be controlled via the F10 key or MIDI CCN 79.
+- `{acc,dec}eleration`: The speaker accelerates (decelerates) at 6 (12) Hz/s.
 
 ## Live Interactions
 
@@ -192,38 +315,39 @@ You can live-control your waveforms with your mouse pointer, touch pad or any MI
 The following example stage defines a resonating low-pass filter whose resonance frequency can be controlled with a MIDI modulation wheel/lever from 0 to 10,000 Hz.
 
 ```yml
-stages:
-  - Filter:
-      kind: LowPass2
-      resonance:
-        Controller:
-          kind: Modulation
-          from: 0.0
-          to: 10000.0
-      quality: 5.0
-      in_buffer: 0
-      out_buffer: AudioOut
-      out_level: 1.0
+Filter:
+  kind: LowPass2
+  resonance:
+    Controller:
+      kind: Modulation
+      map0: 0.0
+      map1: 10000.0
+  quality: 5.0
+  in_buffer: 0
+  out_buffer: AudioOut
+  out_level: 1.0
 ```
 
-If you want to use the mouse's vertical axis for sound control use the Breath controller.
+If you want to use the mouse's vertical axis for sound control use the `Breath` controller.
 
 ```yml
 resonance:
   Controller:
-    kind: Breath
-    from: 0.0
+    map0: Breath
+    map1: 0.0
     to: 10000.0
 ```
 
-If you want to use the touchpad for polyphonic sound control use the KeyPressure property.
+If you want to use the touchpad for polyphonic sound control use the `KeyPressure` property.
 
 ```yml
 resonance:
   Linear:
-    input: KeyPressure
-    from: 0.0
-    to: 10000.0
+    input:
+      Property:
+        kind: KeyPressure
+    map0: 0.0
+    map1: 10000.0
 ```
 
 # Feature List