Write some amount of documentation

docs/samples.md

@@ -0,0 +1,76 @@
+# Samples
+
+Control sample playback with timing, looping, and slice parameters.
+
+## Basic Playback
+
+```forth
+"break" s .           ( play sample from start )
+"break" s 0.5 speed . ( half speed )
+"break" s -1 speed .  ( reverse )
+```
+
+## Time and Position
+
+Control where in the sample to start and end:
+
+```forth
+"break" s 0.25 begin .  ( start at 25% )
+"break" s 0.5 end .     ( end at 50% )
+"break" s 0.1 time .    ( offset start time )
+```
+
+## Duration and Gate
+
+```forth
+"pad" s 0.5 dur .   ( play for 0.5 seconds )
+"pad" s 0.8 gate .  ( gate time as fraction )
+```
+
+## Looping
+
+Fit a sample to a number of beats:
+
+```forth
+"break" s 4 loop .  ( fit to 4 beats )
+```
+
+## Repetition
+
+```forth
+"hat" s 4 repeat .  ( trigger 4 times )
+```
+
+## Voice and Routing
+
+```forth
+"kick" s 1 voice .  ( assign to voice 1 )
+"snare" s 0 orbit . ( route to bus 0 )
+```
+
+## Sample Selection
+
+```forth
+"kick" s 2 n .      ( select sample #2 from folder )
+"kit" s "a" bank .  ( use bank suffix )
+1 cut               ( cut group - stops other sounds in same group )
+```
+
+## Words
+
+| Word | Stack | Description |
+|------|-------|-------------|
+| `time` | (f --) | Set time offset |
+| `repeat` | (n --) | Set repeat count |
+| `dur` | (f --) | Set duration |
+| `gate` | (f --) | Set gate time |
+| `speed` | (f --) | Set playback speed |
+| `begin` | (f --) | Set sample start (0-1) |
+| `end` | (f --) | Set sample end (0-1) |
+| `loop` | (n --) | Fit sample to n beats |
+| `voice` | (n --) | Set voice number |
+| `orbit` | (n --) | Set orbit/bus |
+| `n` | (n --) | Set sample number |
+| `bank` | (str --) | Set sample bank suffix |
+| `cut` | (n --) | Set cut group |
+| `reset` | (n --) | Reset parameter |