From 8e43e1bb3c40c51cb8b4b5251803d17e3d947829 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Forment?= Date: Sat, 7 Mar 2026 11:47:54 +0100 Subject: [PATCH] Feat: document time stretching --- docs/engine/samples.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/engine/samples.md b/docs/engine/samples.md index 5e70b9c..2d9344d 100644 --- a/docs/engine/samples.md +++ b/docs/engine/samples.md @@ -50,6 +50,7 @@ snare sound 0.5 speed . ( play snare at half speed ) | `slice` | 1+ | Divide sample into N equal slices | | `pick` | 0+ | Select which slice to play (0-indexed, wraps) | | `speed` | any | Playback speed multiplier | +| `stretch` | 0+ | Time-stretch factor (pitch-independent) | | `freq` | Hz | Base frequency for pitch tracking | | `fit` | seconds | Stretch/compress sample to fit duration | | `cut` | 0+ | Choke group | @@ -105,6 +106,24 @@ crow sound -1 speed . ( play backwards at nominal speed ) crow sound -4 speed . ( play backwards, 4 times faster ) ``` +## Time Stretching + +The `stretch` parameter changes sample duration without affecting pitch, using a phase vocoder algorithm. This contrasts with `speed`, which changes both tempo and pitch together. + +```forth +kick sound 2 stretch . ( twice as long, same pitch ) +kick sound 0.5 stretch . ( half as long, same pitch ) +kick sound 0 stretch . ( freeze — holds at current position ) +``` + +Combine with `slice` and `pick` for pitch-locked breakbeat manipulation: + +```forth +break sound 8 slice step pick 2 stretch . ( sliced break, stretched x2, original pitch ) +``` + +Reverse playback is not available with `stretch` — use `speed` for that. + ## Fitting to Duration The `fit` parameter stretches or compresses a sample to match a target duration in seconds. This adjusts speed automatically.