BuboBubo/Cagire
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Work on documentation

Browse Source
This commit is contained in:
Raphaël Forment
2026-01-31 15:03:20 +01:00
parent 1903d77ac1
commit c3f8ab5fb4
6 changed files with 500 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
docs/engine_distortion.md Normal file
View File

@@ -0,0 +1,65 @@
# Distortion
Distortion effects add harmonics by nonlinearly shaping the waveform.
## Saturation
Soft saturation using the transfer function `x / (1 + k|x|)`.
```forth
saw 2 distort .
saw 8 distort 0.5 distortvol . ( with volume compensation )
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `distort` | 0+ | Saturation amount |
| `distortvol` | 0-1 | Output volume |
## Wavefolding
Wavefolding reflects the signal when it exceeds ±1, using `sin(x × amount × π/2)`.
```forth
sine 4 fold .
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `fold` | 0+ | Fold amount |
## Wavewrapping
Wavewrapping applies modulo to wrap the signal into the -1 to 1 range.
```forth
saw 3 wrap .
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `wrap` | 0+ | Number of wraps |
## Bit Crushing
Bit crushing quantizes the signal to fewer amplitude levels.
```forth
snare 6 crush . ( 6-bit = 32 levels )
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `crush` | 1-16 | Bit depth |
## Sample Rate Reduction
Sample rate reduction holds each sample for multiple output samples.
```forth
hat 4 coarse . ( 1/4 effective sample rate )
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `coarse` | 1+ | Reduction factor (1 = bypass) |

131
docs/engine_filters.md Normal file
View File

@@ -0,0 +1,131 @@
# Filters
Filters attenuate frequencies above or below a cutoff point.
## Lowpass Filter
The lowpass filter (`lpf`) attenuates frequencies above the cutoff.
```forth
saw 1000 lpf . ( cut above 1000 Hz )
saw 500 lpf 0.8 lpq . ( with resonance )
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `lpf` | Hz | Cutoff frequency |
| `lpq` | 0-1 | Resonance (peak at cutoff) |
## Highpass Filter
The highpass filter (`hpf`) attenuates frequencies below the cutoff.
```forth
kick 200 hpf . ( cut below 200 Hz )
pad 400 hpf 0.3 hpq . ( with resonance )
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `hpf` | Hz | Cutoff frequency |
| `hpq` | 0-1 | Resonance |
## Bandpass Filter
The bandpass filter (`bpf`) attenuates frequencies outside a band around the center frequency.
```forth
noise 1000 bpf 0.7 bpq . ( narrow band around 1000 Hz )
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `bpf` | Hz | Center frequency |
| `bpq` | 0-1 | Resonance (narrower band) |
## Filter Slope
The `ftype` parameter sets the filter slope (rolloff steepness).
| Value | Slope |
|-------|-------|
| `1` | 12 dB/octave |
| `2` | 24 dB/octave (default) |
| `3` | 48 dB/octave |
```forth
saw 800 lpf 3 ftype . ( 48 dB/oct lowpass )
```
## Filter Envelope
Filters can be modulated by an ADSR envelope. The envelope multiplies the base cutoff:
```
final_cutoff = lpf + (lpe × envelope × lpf)
```
When the envelope is at 1.0 and `lpe` is 1.0, the cutoff doubles. When the envelope is at 0, the cutoff equals `lpf`.
```forth
saw 200 lpf 2 lpe 0.01 lpa 0.3 lpd . ( cutoff sweeps from 600 Hz down to 200 Hz )
```
| Parameter | Description |
|-----------|-------------|
| `lpe` | Envelope depth (multiplier, 1.0 = double cutoff at peak) |
| `lpa` | Attack time in seconds |
| `lpd` | Decay time in seconds |
| `lps` | Sustain level (0-1) |
| `lpr` | Release time in seconds |
The same pattern works for highpass (`hpe`, `hpa`, etc.) and bandpass (`bpe`, `bpa`, etc.).
## Ladder Filters
Ladder filters use a different algorithm (Moog-style) with self-oscillation at high resonance.
```forth
saw 800 llpf 0.7 llpq . ( ladder lowpass )
saw 300 lhpf 0.5 lhpq . ( ladder highpass )
saw 1000 lbpf 0.8 lbpq . ( ladder bandpass )
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `llpf` | Hz | Ladder lowpass cutoff |
| `llpq` | 0-1 | Ladder lowpass resonance |
| `lhpf` | Hz | Ladder highpass cutoff |
| `lhpq` | 0-1 | Ladder highpass resonance |
| `lbpf` | Hz | Ladder bandpass cutoff |
| `lbpq` | 0-1 | Ladder bandpass resonance |
Ladder filters share the lowpass envelope parameters (`lpe`, `lpa`, etc.).
## EQ
The 3-band EQ applies shelf and peak filters at fixed frequencies.
```forth
kick 3 eqlo -2 eqhi . ( +3 dB at 200 Hz, -2 dB at 5000 Hz )
snare 2 eqmid . ( +2 dB at 1000 Hz )
```
| Parameter | Frequency | Type |
|-----------|-----------|------|
| `eqlo` | 200 Hz | Low shelf (dB) |
| `eqmid` | 1000 Hz | Peak (dB) |
| `eqhi` | 5000 Hz | High shelf (dB) |
## Tilt EQ
Tilt EQ applies a high shelf at 800 Hz with up to ±6 dB gain.
```forth
pad -0.5 tilt . ( -3 dB above 800 Hz )
hat 0.5 tilt . ( +3 dB above 800 Hz )
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `tilt` | -1 to 1 | High shelf gain (-1 = -6 dB, 0 = flat, 1 = +6 dB) |

132
docs/engine_modulation.md Normal file
View File

@@ -0,0 +1,132 @@
# Modulation
Modulation effects vary parameters over time using LFOs or envelopes.
## Vibrato
Vibrato modulates pitch with an LFO.
```forth
saw 5 vib 0.5 vibmod . ( 5 Hz, 0.5 semitone depth )
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `vib` | Hz | LFO rate |
| `vibmod` | semitones | Modulation depth |
| `vibshape` | shape | LFO waveform (sine, tri, saw, square) |
## Pitch Envelope
The pitch envelope applies an ADSR to the oscillator frequency.
```forth
sine 100 freq 24 penv 0.001 patt 0.1 pdec .
```
| Parameter | Description |
|-----------|-------------|
| `penv` | Envelope depth in semitones |
| `patt` | Attack time in seconds |
| `pdec` | Decay time in seconds |
| `psus` | Sustain level (0-1) |
| `prel` | Release time in seconds |
## Glide
Glide interpolates between pitch changes over time.
```forth
saw c4 0.1 glide . ( 100ms glide )
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `glide` | seconds | Glide time |
## FM Synthesis
FM modulates the carrier frequency with a modulator oscillator.
```forth
sine 440 freq 2 fm 2 fmh . ( modulator at 2× carrier frequency )
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `fm` | 0+ | Modulation index |
| `fmh` | ratio | Harmonic ratio (modulator / carrier) |
| `fmshape` | shape | Modulator waveform |
FM has its own envelope (`fme`, `fma`, `fmd`, `fms`, `fmr`).
## Amplitude Modulation
AM multiplies the signal by an LFO.
```forth
pad 4 am 0.5 amdepth . ( 4 Hz tremolo )
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `am` | Hz | LFO rate |
| `amdepth` | 0-1 | Modulation depth |
| `amshape` | shape | LFO waveform |
## Ring Modulation
Ring modulation multiplies two signals, producing sum and difference frequencies.
```forth
saw 150 rm 0.8 rmdepth . ( ring mod at 150 Hz )
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `rm` | Hz | Modulator frequency |
| `rmdepth` | 0-1 | Modulation depth |
| `rmshape` | shape | Modulator waveform |
## Phaser
Phaser sweeps notches through the frequency spectrum using allpass filters.
```forth
pad 0.5 phaser 0.6 phaserdepth .
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `phaser` | Hz | Sweep rate |
| `phaserdepth` | 0-1 | Sweep depth |
| `phasersweep` | cents | Sweep range |
| `phasercenter` | Hz | Center frequency |
## Flanger
Flanger mixes the signal with a short modulated delay (0.5-10ms).
```forth
pad 0.3 flanger 0.7 flangerdepth 0.5 flangerfeedback .
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `flanger` | Hz | Modulation rate |
| `flangerdepth` | 0-1 | Modulation depth |
| `flangerfeedback` | 0-0.95 | Feedback amount |
## Chorus
Chorus uses multiple modulated delay lines with 120° phase offset for stereo width.
```forth
pad 1 chorus 0.4 chorusdepth 20 chorusdelay .
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `chorus` | Hz | Modulation rate |
| `chorusdepth` | 0-1 | Modulation depth |
| `chorusdelay` | ms | Base delay time |

118
docs/engine_space.md Normal file
View File

@@ -0,0 +1,118 @@
# Space & Time
Spatial effects position sounds in the stereo field and add depth through delays and reverbs.
## Pan
Pan positions a sound in the stereo field.
```forth
hat -0.5 pan . ( slightly left )
perc 1 pan . ( hard right )
kick 0 pan . ( center )
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `pan` | -1 to 1 | Stereo position (-1 = left, 0 = center, 1 = right) |
## Width
Width controls the stereo spread using mid-side processing.
```forth
pad 1.5 width . ( wider stereo )
pad 0 width . ( mono )
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `width` | 0+ | Stereo width (0 = mono, 1 = unchanged, 2 = exaggerated) |
## Haas Effect
The Haas effect delays one channel slightly, creating a sense of stereo width and spatial placement.
```forth
snare 15 haas . ( 15ms delay on right channel )
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `haas` | ms | Delay time (1-10ms = subtle width, 10-35ms = distinct echo) |
## Delay
Delay is a send effect that creates echoes. The `delay` parameter sets how much signal is sent to the delay bus.
```forth
snare 0.3 delay 0.25 delaytime 0.5 delayfeedback .
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `delay` | 0-1 | Send level |
| `delaytime` | seconds | Delay time |
| `delayfeedback` | 0-0.95 | Feedback amount |
| `delaytype` | type | Delay algorithm |
### Delay Types
| Type | Description |
|------|-------------|
| `standard` | Clean digital repeats |
| `pingpong` | Bounces between left and right |
| `tape` | Each repeat gets darker (analog warmth) |
| `multitap` | 4 taps with swing control via feedback |
```forth
snare 0.4 delay pingpong delaytype .
pad 0.3 delay tape delaytype .
```
## Reverb
Reverb is a send effect that simulates acoustic spaces. The `verb` parameter sets the send level.
```forth
snare 0.2 verb 2 verbdecay .
pad 0.4 verb 4 verbdecay 0.7 verbdamp .
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `verb` | 0-1 | Send level |
| `verbdecay` | seconds | Reverb tail length |
| `verbdamp` | 0-1 | High frequency damping |
| `verbpredelay` | ms | Initial delay before reverb |
| `verbdiff` | 0-1 | Diffusion (smears transients) |
| `verbtype` | type | Reverb algorithm |
### Reverb Types
| Type | Description |
|------|-------------|
| `dattorro` | Plate reverb, bright and metallic shimmer |
| `fdn` | Hall reverb, dense and smooth |
```forth
snare 0.3 verb dattorro verbtype . ( plate )
pad 0.5 verb fdn verbtype . ( hall )
```
## Comb Filter
The comb filter creates resonant pitched delays, useful for Karplus-Strong string synthesis and metallic tones.
```forth
white 0.5 comb 220 combfreq 0.9 combfeedback . ( plucked string )
```
| Parameter | Range | Description |
|-----------|-------|-------------|
| `comb` | 0-1 | Send level |
| `combfreq` | Hz | Resonant frequency |
| `combfeedback` | 0-0.99 | Feedback (higher = longer decay) |
| `combdamp` | 0-1 | High frequency damping |
Higher feedback creates longer, ringing tones. Add damping for more natural string-like decay.

43
docs/engine_words.md Normal file
View File

@@ -0,0 +1,43 @@
# Words & Sounds
Word definitions let you abstract sound design into reusable units.
## Defining Sounds
```forth
: lead "saw" s 0.3 gain 1200 lpf ;
```
Use it with different notes:
```forth
c4 note lead .
e4 note lead .
```
## Self-Contained Words
Include the emit to make the word play directly:
```forth
: kk "kick" s 1 decay . ;
: hh "hihat" s 0.5 gain 0.5 decay . ;
```
Steps become simple:
```forth
kk
0.5 at hh
```
## Effect Presets
```forth
: dark 800 lpf 0.6 lpq ;
: wet 0.7 verb 8 verbdiff ;
```
```forth
c4 note saw s dark wet .
```