Feat: refactoring codebase

docs/engine/sources.md

@@ -0,0 +1,92 @@
+# Sources
+
+The audio engine provides a variety of sound sources. Use the `sound` word (or `s` for short) to select one.
+
+## Basic Oscillators
+
+| Name | Description |
+|------|-------------|
+| `sine` | Pure sinusoid, smooth and mellow |
+| `tri` | Triangle wave, warmer than sine, naturally band-limited |
+| `saw` | Bright sawtooth with anti-aliasing, rich in harmonics |
+| `zaw` | Raw sawtooth without anti-aliasing, lo-fi character |
+| `pulse`, `square` | Variable-width pulse wave with anti-aliasing |
+| `pulze`, `zquare` | Raw pulse without anti-aliasing, 8-bit feel |
+
+`pulse` and `pulze` respond to the `pw` parameter (0.0-1.0) for pulse width. At 0.5 you get a square wave.
+
+### Phase Shaping
+
+All oscillators support phase shaping for timbral variation:
+
+| Parameter | Range | Effect |
+|-----------|-------|--------|
+| `size` | 0-256 | Phase quantization (lo-fi, chiptune). |
+| `mult` | 0.25-16 | Phase multiplier (harmonic overtones). |
+| `warp` | -1 to 1 | Power curve asymmetry. |
+| `mirror` | 0-1 | Phase reflection point. |
+
+These are super useful to get the most out of your oscillators.
+
+### Sub Oscillator
+
+Add a sub oscillator layer to any basic oscillator:
+
+| Parameter | Range | Effect |
+|-----------|-------|--------|
+| `sub` | 0-1 | Mix level |
+| `suboct` | 1-3 | Octaves below main. |
+| `subwave` | tri/sine/square | Sub waveform. |
+
+## Noise
+
+| Name | Description |
+|------|-------------|
+| `white` | Equal energy across all frequencies, bright and hissy. |
+| `pink` | -3dB/octave rolloff, equal energy per octave, natural. |
+| `brown` | -6dB/octave rolloff, deep rumbling, random walk. |
+
+Noise sources ignore pitch. Use filters to shape the spectrum.
+
+## Live Input
+
+| Name | Description |
+|------|-------------|
+| `live`, `livein`, `mic` | Live audio input from microphone or line-in |
+
+All filter and effect parameters apply to the input signal.
+
+## Plaits Engines
+
+The Plaits engines come from Mutable Instruments and provide a range of synthesis methods. Beware, these sources can be quite CPU hungry. All share three control parameters (`0.0`-`1.0`):
+
+| Parameter | Controls |
+|-----------|----------|
+| `harmonics` | Harmonic content, structure, detuning. |
+| `timbre` | Brightness, tonal color. |
+| `morph` | Smooth transitions between variations. |
+
+### Pitched
+
+| Name | Description |
+|------|-------------|
+| `modal` | Struck/plucked resonant bodies (strings, plates, tubes). |
+| `va`, `analog` | Virtual analog with waveform sync and crossfading. |
+| `ws`, `waveshape` | Waveshaper and wavefolder. |
+| `fm2` | Two-operator FM synthesis with feedback. |
+| `grain` | Granular formant oscillator (vowel-like). |
+| `additive` | Harmonic additive synthesis. |
+| `wavetable` | Built-in Plaits wavetables (four 8x8 banks). |
+| `chord` | Four-note chord generator. |
+| `swarm` | Granular cloud of enveloped sawtooths. |
+| `pnoise` | Clocked noise through multimode filter. |
+
+### Percussion
+
+| Name | Description |
+|------|-------------|
+| `kick`, `bass` | 808-style bass drum. |
+| `snare` | Analog snare drum with tone/noise balance. |
+| `hihat`, `hat` | Metallic 808-style hi-hat. |
+
+Percussions are super hard to use correctly, because you need to tweak their envelope correctly.