Work on documentation

docs/engine_settings.md

@@ -38,18 +38,86 @@ Smaller buffers mean lower latency but higher CPU load. Larger buffers are safer
 
 Start with 512. Lower it if you need tighter timing. Raise it if you hear glitches.
 
-### Samples
+## Samples
 
-The engine indexes audio files from your sample directories. Add directories with `A`, remove with `D`. The sample count shows how many files are indexed. You can load as many sample banks as you want, they are not really loaded into memory but _lazily loaded_. They are loaded on demand when you play a sample. Samples are referenced by filename without extension: 
+The engine indexes audio files from your sample directories. Add directories with `A`, remove with `D`. The sample count shows how many files are indexed.
+
+### Supported Formats
+
+- WAV (.wav)
+- MP3 (.mp3)
+- OGG Vorbis (.ogg)
+- FLAC (.flac)
+- AIFF (.aiff, .aif)
+- AAC (.aac)
+- M4A (.m4a)
+
+### Lazy Loading
+
+Samples are not loaded into memory at startup. They are decoded on demand when first played. This means you can have thousands of samples indexed without using much RAM until you actually use them.
+
+### Folder Organization
+
+The scanner looks at top-level files and one level of subdirectories:
+
+```
+samples/
+├── kick.wav           -> "kick"
+├── snare.wav          -> "snare"
+├── hats/
+│   ├── closed.wav     -> "hats" n 0
+│   ├── open.wav       -> "hats" n 1
+│   └── pedal.wav      -> "hats" n 2
+└── breaks/
+    ├── amen.wav       -> "breaks" n 0
+    └── think.wav      -> "breaks" n 1
+```
+
+Top-level files are named by their filename (without extension). Files inside folders are sorted alphabetically and numbered starting from 0.
+
+### Playing Samples
+
+Reference samples by name:
 
 ```forth
-kick s .       ;; plays kick.wav, kick.mp3, etc.
+kick s .              ;; play kick.wav
+snare s 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)
+```
+
+The index wraps around. If you have 3 samples and request `5 n`, you get index 2 (because 5 % 3 = 2).
+
+### Sample Variations with Bank
+
+The `bank` parameter lets you organize variations:
+
+```
+samples/
+├── kick.wav          -> default
+├── kick_a.wav        -> bank "a"
+├── kick_b.wav        -> bank "b"
+└── kick_hard.wav     -> bank "hard"
+```
+
+```forth
+kick s .              ;; plays kick.wav
+kick s a bank .       ;; plays kick_a.wav
+kick s hard bank .    ;; plays kick_hard.wav
+```
+
+If the banked version does not exist, it falls back to the default.
+
 ## Troubleshooting
 
 * **No sound**: Check output device selection.
-    * Try the test sound (`t`) on Engine page).
+  * Try the test sound (`t`) on Engine page).
 
 * **Glitches/crackling**: Increase buffer size, restart the Engine.