From 3373fa39a6be2d2d3765dcbd52b63c30e4f3b10a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Va=CC=81clav=20Volhejn?= <vaclav.volhejn@gmail.com>
Date: Sat, 18 Oct 2025 12:14:39 +0200
Subject: [PATCH 1/3] Fix the documentation of `stretch`

---
 packages/core/controls.mjs | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/packages/core/controls.mjs b/packages/core/controls.mjs
index 7e3c2a8e2..130608447 100644
--- a/packages/core/controls.mjs
+++ b/packages/core/controls.mjs
@@ -1935,12 +1935,16 @@ export const { compressorRelease } = registerControl('compressorRelease');
 export const { speed } = registerControl('speed');
 
 /**
- * Changes the speed of sample playback, i.e. a cheap way of changing pitch.
+ * Changes the pitch of the sample without changing its speed.
+ * The frequencies are multiplied by (factor + 1) for positive numbers
+ * and by max(factor / 4 + 1, 0) for negative numbers.
+ * So tuning up by octaves can be done with 1, 3, 7, ...
+ * and tuning down by octaves with -2, -3, -3.5...
  *
  * @name stretch
- * @param {number | Pattern} factor -inf to inf, negative numbers play the sample backwards.
+ * @param {number | Pattern} factor between `-4` and `inf`. Positive increases pitch, 0 does nothing, negative decreases the pitch.
  * @example
- * s("gm_flute").stretch("1 2 .5")
+ * s("gm_flute").stretch("<3 2 1 0 -2>")
  *
  */
 export const { stretch } = registerControl('stretch');

From 7d948fd1a76cb92d0da8a29a8710a977fa010083 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Va=CC=81clav=20Volhejn?= <vaclav.volhejn@gmail.com>
Date: Sat, 18 Oct 2025 12:25:15 +0200
Subject: [PATCH 2/3] Fix example snapshot

---
 packages/core/controls.mjs                |  2 +-
 test/__snapshots__/examples.test.mjs.snap | 16 ++++------------
 2 files changed, 5 insertions(+), 13 deletions(-)

diff --git a/packages/core/controls.mjs b/packages/core/controls.mjs
index 130608447..03de38666 100644
--- a/packages/core/controls.mjs
+++ b/packages/core/controls.mjs
@@ -1944,7 +1944,7 @@ export const { speed } = registerControl('speed');
  * @name stretch
  * @param {number | Pattern} factor between `-4` and `inf`. Positive increases pitch, 0 does nothing, negative decreases the pitch.
  * @example
- * s("gm_flute").stretch("<3 2 1 0 -2>")
+ * s("gm_flute").stretch("<2 1 0 -2>")
  *
  */
 export const { stretch } = registerControl('stretch');
diff --git a/test/__snapshots__/examples.test.mjs.snap b/test/__snapshots__/examples.test.mjs.snap
index 73278947d..a23806c1c 100644
--- a/test/__snapshots__/examples.test.mjs.snap
+++ b/test/__snapshots__/examples.test.mjs.snap
@@ -10439,18 +10439,10 @@ exports[`runs examples > example "stepcat" example index 1 1`] = `
 
 exports[`runs examples > example "stretch" example index 0 1`] = `
 [
-  "[ (0/1 → 1/3) ⇝ 1/1 | s:gm_flute stretch:1 ]",
-  "[ 0/1 ⇜ (1/3 → 2/3) ⇝ 1/1 | s:gm_flute stretch:2 ]",
-  "[ 0/1 ⇜ (2/3 → 1/1) | s:gm_flute stretch:0.5 ]",
-  "[ (1/1 → 4/3) ⇝ 2/1 | s:gm_flute stretch:1 ]",
-  "[ 1/1 ⇜ (4/3 → 5/3) ⇝ 2/1 | s:gm_flute stretch:2 ]",
-  "[ 1/1 ⇜ (5/3 → 2/1) | s:gm_flute stretch:0.5 ]",
-  "[ (2/1 → 7/3) ⇝ 3/1 | s:gm_flute stretch:1 ]",
-  "[ 2/1 ⇜ (7/3 → 8/3) ⇝ 3/1 | s:gm_flute stretch:2 ]",
-  "[ 2/1 ⇜ (8/3 → 3/1) | s:gm_flute stretch:0.5 ]",
-  "[ (3/1 → 10/3) ⇝ 4/1 | s:gm_flute stretch:1 ]",
-  "[ 3/1 ⇜ (10/3 → 11/3) ⇝ 4/1 | s:gm_flute stretch:2 ]",
-  "[ 3/1 ⇜ (11/3 → 4/1) | s:gm_flute stretch:0.5 ]",
+  "[ 0/1 → 1/1 | s:gm_flute stretch:3 ]",
+  "[ 1/1 → 2/1 | s:gm_flute stretch:2 ]",
+  "[ 2/1 → 3/1 | s:gm_flute stretch:1 ]",
+  "[ 3/1 → 4/1 | s:gm_flute stretch:-2 ]",
 ]
 `;
 

From 54fd877be1272031972f9b0df183874c11f3e32f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Va=CC=81clav=20Volhejn?= <vaclav.volhejn@gmail.com>
Date: Sat, 18 Oct 2025 13:19:18 +0200
Subject: [PATCH 3/3] Update snapshot

---
 test/__snapshots__/examples.test.mjs.snap | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/test/__snapshots__/examples.test.mjs.snap b/test/__snapshots__/examples.test.mjs.snap
index a23806c1c..9eebfed35 100644
--- a/test/__snapshots__/examples.test.mjs.snap
+++ b/test/__snapshots__/examples.test.mjs.snap
@@ -10439,9 +10439,9 @@ exports[`runs examples > example "stepcat" example index 1 1`] = `
 
 exports[`runs examples > example "stretch" example index 0 1`] = `
 [
-  "[ 0/1 → 1/1 | s:gm_flute stretch:3 ]",
-  "[ 1/1 → 2/1 | s:gm_flute stretch:2 ]",
-  "[ 2/1 → 3/1 | s:gm_flute stretch:1 ]",
+  "[ 0/1 → 1/1 | s:gm_flute stretch:2 ]",
+  "[ 1/1 → 2/1 | s:gm_flute stretch:1 ]",
+  "[ 2/1 → 3/1 | s:gm_flute stretch:0 ]",
   "[ 3/1 → 4/1 | s:gm_flute stretch:-2 ]",
 ]
 `;