Fix: update docs about snd

This commit is contained in:
2026-03-06 08:40:41 +01:00
parent f273470eaf
commit d055d2bfc6
23 changed files with 228 additions and 200 deletions

View File

@@ -9,8 +9,8 @@ All time values are in **steps**, just like `attack`, `decay`, and `release`. At
Oscillate a parameter between two values.
```forth
saw s 200 4000 4 lfo lpf . ( sweep filter over 4 steps )
saw s 0.3 0.7 2 tlfo pan . ( triangle pan over 2 steps )
saw snd 200 4000 4 lfo lpf . ( sweep filter over 4 steps )
saw snd 0.3 0.7 2 tlfo pan . ( triangle pan over 2 steps )
```
| Word | Shape | Output |
@@ -27,8 +27,8 @@ Stack effect: `( min max period -- str )`
Transition from one value to another over a duration.
```forth
saw s 0 1 0.5 slide gain . ( fade in over half a step )
saw s 200 4000 8 sslide lpf . ( smooth sweep over 8 steps )
saw snd 0 1 0.5 slide gain . ( fade in over half a step )
saw snd 200 4000 8 sslide lpf . ( smooth sweep over 8 steps )
```
| Word | Curve | Output |
@@ -44,9 +44,9 @@ Stack effect: `( start end dur -- str )`
Randomize a parameter within a range, retriggering at a given period.
```forth
saw s 200 4000 2 jit lpf . ( new random value every 2 steps )
saw s 200 4000 2 sjit lpf . ( same but smoothly interpolated )
saw s 200 4000 1 drunk lpf . ( random walk, each step )
saw snd 200 4000 2 jit lpf . ( new random value every 2 steps )
saw snd 200 4000 2 sjit lpf . ( same but smoothly interpolated )
saw snd 200 4000 1 drunk lpf . ( random walk, each step )
```
| Word | Behavior | Output |
@@ -62,7 +62,7 @@ Stack effect: `( min max period -- str )`
Define a multi-segment envelope for a parameter. Provide a start value, then pairs of target and duration.
```forth
saw s 0 1 0.1 0.7 0.5 0 8 env gain .
saw snd 0 1 0.1 0.7 0.5 0 8 env gain .
```
This creates: start at `0`, rise to `1` in `0.1` steps, drop to `0.7` in `0.5` steps, fall to `0` in `8` steps.
@@ -74,7 +74,7 @@ Stack effect: `( start target1 dur1 [target2 dur2 ...] -- str )`
Modulation words return strings, so they compose naturally with the rest of the language. Use them anywhere a parameter value is expected.
```forth
saw s
saw snd
200 4000 4 lfo lpf
0.3 0.7 8 tlfo pan
0 1 0.1 0.7 0.5 0 8 env gain

View File

@@ -7,7 +7,7 @@ Cagire includes an audio engine called `Doux`. No external software is needed to
When you write a Forth script and emit (`.`), the script produces a command string. This command travels to the audio engine, which interprets it and creates a voice. The voice plays until its envelope finishes or until it is killed by another voice. You can also spawn infinite voices, but you will need to manage their lifecycle manually, otherwise they will never stop.
```forth
saw s c4 note 0.8 gain 0.3 verb .
saw snd c4 note 0.8 gain 0.3 verb .
```
## Voices
@@ -24,7 +24,7 @@ Press `r` on the Engine page to reset the peak counter.
After selecting a sound source, you add parameters. Each parameter word takes a value from the stack and stores it in the command register:
```forth
saw s
saw snd
c4 note ;; pitch
0.5 gain ;; volume
0.1 attack ;; envelope attack time
@@ -42,14 +42,14 @@ Use `all` to apply parameters globally. Global parameters persist across all pat
```forth
;; Prospective: set params before emitting
500 lpf 0.5 verb all
kick s 60 note . ;; gets lpf=500 verb=0.5
hat s 70 note . ;; gets lpf=500 verb=0.5
kick snd 60 note . ;; gets lpf=500 verb=0.5
hat snd 70 note . ;; gets lpf=500 verb=0.5
```
```forth
;; Retroactive: patch already-emitted sounds
kick s 60 note .
hat s 70 note .
kick snd 60 note .
hat snd 70 note .
500 lpf 0.5 verb all ;; both outputs get lpf and verb
```
@@ -57,17 +57,17 @@ Per-sound parameters override global ones:
```forth
500 lpf all
kick s 2000 lpf . ;; lpf=2000 (per-sound wins)
hat s . ;; lpf=500 (global)
kick snd 2000 lpf . ;; lpf=2000 (per-sound wins)
hat snd . ;; lpf=500 (global)
```
Use `noall` to clear global parameters:
```forth
500 lpf all
kick s . ;; gets lpf
kick snd . ;; gets lpf
noall
hat s . ;; no lpf
hat snd . ;; no lpf
```
## Controlling Existing Voices

View File

@@ -79,16 +79,16 @@ Top-level files are named by their filename (without extension). Files inside fo
Reference samples by name:
```forth
kick s . ;; play kick.wav
snare s 0.5 gain . ;; play snare at half volume
kick snd . ;; play kick.wav
snare snd 0.5 gain . ;; play snare at half volume
```
For samples in folders, use `n` to select which one:
```forth
hats s 0 n . ;; play hats/closed.wav (index 0)
hats s 1 n . ;; play hats/open.wav (index 1)
hats s 2 n . ;; play hats/pedal.wav (index 2)
hats snd 0 n . ;; play hats/closed.wav (index 0)
hats snd 1 n . ;; play hats/open.wav (index 1)
hats snd 2 n . ;; play hats/pedal.wav (index 2)
```
The index wraps around. If you have 3 samples and request `5 n`, you get index 2 (because 5 % 3 = 2).
@@ -106,9 +106,9 @@ samples/
```
```forth
kick s . ;; plays kick.wav
kick s a bank . ;; plays kick_a.wav
kick s hard bank . ;; plays kick_hard.wav
kick snd . ;; plays kick.wav
kick snd a bank . ;; plays kick_a.wav
kick snd hard bank . ;; plays kick_hard.wav
```
If the banked version does not exist, it falls back to the default.

View File

@@ -1,6 +1,6 @@
# Sources
The audio engine provides a variety of sound sources. Use the `sound` word (or `s` for short) to select one.
The audio engine provides a variety of sound sources. Use the `sound` word (or `snd` for short) to select one.
## Basic Oscillators

View File

@@ -5,7 +5,7 @@ Word definitions let you abstract sound design into reusable units.
## Defining Sounds
```forth
: lead "saw" s 0.3 gain 1200 lpf ;
: lead "saw" snd 0.3 gain 1200 lpf ;
```
Use it with different notes:
@@ -20,8 +20,8 @@ e4 note lead .
Include the emit to make the word play directly:
```forth
: kk "kick" s 1 decay . ;
: hh "hihat" s 0.5 gain 0.5 decay . ;
: kk "kick" snd 1 decay . ;
: hh "hihat" snd 0.5 gain 0.5 decay . ;
```
Steps become simple:
@@ -39,5 +39,5 @@ kk
```
```forth
c4 note saw s dark wet .
c4 note saw snd dark wet .
```