Feat: refactoring codebase

docs/engine/samples.md

@@ -0,0 +1,126 @@
+# Samples
+
+The `sample` source plays audio files from disk with pitch tracking.
+
+## Loading Samples
+
+There are two ways to load samples:
+
+* **From the app:** Navigate to the Engine view and find the Samples section. Press `A` to open a file browser, then select a folder containing your samples. Press `D` to remove the last added path.
+
+* **From the command line:** Use the `-s` flag when launching Cagire:
+
+```
+cagire -s ~/samples -s ~/more-samples
+```
+
+The engine scans these directories and builds a registry of available samples. Samples load in the background without blocking audio. Supported file formats are `.wav`, `.mp3`, `.ogg`, `.flac` and `.aiff`.
+
+## Folder Organization
+
+```
+samples/
+├── kick.wav           → "kick"
+├── snare.wav          → "snare"
+└── hats/
+    ├── closed.wav     → "hats" n 0
+    ├── open.wav       → "hats" n 1
+    └── pedal.wav      → "hats" n 2
+```
+
+Folders at the root of your directory are used as the name of a sample bank. Folders create sample banks where each file gets an index. Files are sorted alphabetically and assigned indices starting from `0`.
+
+## Playing Samples
+
+```forth
+kick sound .                     ( play kick sample )
+hats sound 2 n .                 ( play third hat sample )
+snare sound  0.5 speed .         ( play snare at half speed )
+```
+
+## Parameters
+
+| Parameter | Range | Description |
+|-----------|-------|-------------|
+| `n` | 0+ | Sample index within a folder (wraps around) |
+| `begin` | 0-1 | Playback start position |
+| `end` | 0-1 | Playback end position |
+| `speed` | any | Playback speed multiplier |
+| `freq` | Hz | Base frequency for pitch tracking |
+| `fit` | seconds | Stretch/compress sample to fit duration |
+| `cut` | 0+ | Choke group |
+
+## Slicing with Begin/End
+
+The `begin` and `end` parameters define what portion of the sample plays. Values are normalized from 0 (start) to 1 (end).
+
+```forth
+kick sound 0.25 begin 0.75 end .   ( play middle half )
+kick sound 0.5 begin .             ( play second half )
+kick sound 0.5 end .               ( play first half )
+```
+
+If begin is greater than end, they swap automatically.
+
+## Speed and Pitch
+
+The `speed` parameter affects both tempo and pitch. A speed of 2 plays twice as fast and an octave higher.
+
+```forth
+snare sound 2 speed .              ( double speed, octave up )
+snare sound 0.5 speed .            ( half speed, octave down )
+snare sound -1 speed .             ( play in reverse )
+```
+
+For pitched playback, use `freq` or note names. The sample's base frequency defaults to middle C (261.626 Hz).
+
+```forth
+kick sound 440 freq .              ( play at A4 )
+kick sound c4 .                    ( play at C4 )
+```
+
+Negative speed will reverse the sample and play it backwards.
+
+```forth
+crow sound -1 speed .              ( play backwards at nominal speed )
+crow sound -4 speed .              ( play backwards, 4 times faster )
+```
+
+## Fitting to Duration
+
+The `fit` parameter stretches or compresses a sample to match a target duration in seconds. This adjusts speed automatically.
+
+```forth
+kick sound 0.25 fit .              ( fit kick into quarter second )
+snare sound beat fit .             ( fit snare to one beat )
+```
+
+## Choke Groups
+
+The `cut` parameter assigns a sample to a choke group. When a new sample with the same cut value plays, it kills any currently playing samples in that group.
+
+```forth
+hihat_closed sound 1 cut .         ( choke group 1 )
+hihat_open sound 1 cut .           ( kills closed hat, starts open )
+```
+
+This is essential for realistic hi-hat behavior where open and closed hats shouldn't overlap.
+
+## Bank Variations
+
+Add `_suffix` to sample names to create variations that share the same base name.
+
+```
+samples/
+├── kick.wav
+├── kick_hard.wav
+├── kick_soft.wav
+```
+
+Select variations with the `bank` parameter:
+
+```forth
+kick sound .                       ( plays kick.wav )
+kick sound hard bank .             ( plays kick_hard.wav )
+kick sound soft bank .             ( plays kick_soft.wav )
+```