Feat: docs should be good enough

This commit is contained in:
2026-03-01 19:38:52 +01:00
parent db44f9b98e
commit 2d3094464f
3 changed files with 368 additions and 193 deletions

View File

@@ -13,10 +13,17 @@ Every step has a duration. By default, sounds emit at the very start of that dur
Push multiple values before calling `at` to get multiple emits from a single `.`:
```forth
0 0.5 at kick s . ;; two kicks: one at start, one at midpoint
0 0.25 0.5 0.75 at hat s . ;; four hats, evenly spaced
0 0.5 at kick s .
```
Two kicks: one at start, one at midpoint.
```forth
0 0.25 0.5 0.75 at hat s .
```
Four hats, evenly spaced.
The deltas persist across multiple `.` calls until `clear` or a new `at`:
```forth
@@ -33,10 +40,10 @@ Without `arp`, deltas multiply with polyphonic voices. If you have 3 notes and 2
```forth
0 0.5 at
c4 e4 g4 note sine s . ;; 6 emits: 3 notes x 2 deltas
c4 e4 g4 note 1.5 decay sine s .
```
This is a chord played twice per step.
6 emits: 3 notes x 2 deltas. A chord played twice per step.
## 1:1 Pairing: at With arp
@@ -44,16 +51,20 @@ This is a chord played twice per step.
```forth
0 0.33 0.66 at
c4 e4 g4 arp note sine s . ;; c4 at 0, e4 at 0.33, g4 at 0.66
c4 e4 g4 arp note 0.5 decay sine s .
```
C4 at 0, E4 at 0.33, G4 at 0.66.
If the lists differ in length, the shorter one wraps around:
```forth
0 0.25 0.5 0.75 at
c4 e4 arp note sine s . ;; c4, e4, c4, e4 at 4 time points
c4 e4 arp note 0.3 decay sine s .
```
C4, E4, C4, E4 — the shorter list wraps to fill 4 time points.
This is THE key distinction. Without `arp`: every note at every time. With `arp`: one note per time slot.
## Generating Deltas
@@ -89,12 +100,18 @@ Geometric spacing via `geom..`:
Wrap `at` expressions in quotations for conditional timing:
```forth
( 0 0.25 0.5 0.75 at ) 2 every ;; 16th-note hats every other bar
( 0 0.25 0.5 0.75 at ) 2 every
hat s .
```
( 0 0.5 at ) 0.5 chance ;; 50% chance of double-hit
16th-note hats every other bar.
```forth
( 0 0.5 at ) 0.5 chance
kick s .
```
50% chance of double-hit.
When the quotation doesn't execute, no deltas are set -- you get the default single emit at beat start.