Merge branch 'main' into docs

packages/core/pattern.mjs

@@ -2028,6 +2028,16 @@ export const bypass = register('bypass', function (on, pat) {
   return on ? silence : pat;
 });
 
+/**
+ * Loops the pattern inside at `offset` for `cycles`.
+ * @param {number} offset start point of loop in cycles
+ * @param {number} cycles loop length in cycles
+ * @example
+ * // Looping a portion of randomness
+ * note(irand(8).segment(4).scale('C3 minor')).ribbon(1337, 2)
+ */
+export const ribbon = register('ribbon', (offset, cycles, pat) => pat.early(offset).restart(pure(1).slow(cycles)));
+
 // sets absolute duration of haps
 // TODO - fix
 export const duration = register('duration', function (value, pat) {

packages/core/test/pattern.test.mjs

@@ -914,6 +914,13 @@ describe('Pattern', () => {
       expect(run(4).firstCycle()).toStrictEqual(sequence(0, 1, 2, 3).firstCycle());
     });
   });
+  describe('ribbon', () => {
+    it('Can ribbon', () => {
+      expect(cat(0, 1, 2, 3, 4, 5, 6, 7).ribbon(2, 4).fast(4).firstCycle()).toStrictEqual(
+        sequence(2, 3, 4, 5).firstCycle(),
+      );
+    });
+  });
   describe('linger', () => {
     it('Can linger on the first quarter of a cycle', () => {
       expect(sequence(0, 1, 2, 3, 4, 5, 6, 7).linger(0.25).firstCycle()).toStrictEqual(

test/__snapshots__/examples.test.mjs.snap

@@ -3066,6 +3066,27 @@ exports[`runs examples > example "rev" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "ribbon" example index 0 1`] = `
+[
+  "[ 0/1 → 1/4 | note:C3 ]",
+  "[ 1/4 → 1/2 | note:G3 ]",
+  "[ 1/2 → 3/4 | note:Eb3 ]",
+  "[ 3/4 → 1/1 | note:Bb3 ]",
+  "[ 1/1 → 5/4 | note:C3 ]",
+  "[ 5/4 → 3/2 | note:D3 ]",
+  "[ 3/2 → 7/4 | note:G3 ]",
+  "[ 7/4 → 2/1 | note:Eb3 ]",
+  "[ 2/1 → 9/4 | note:C3 ]",
+  "[ 9/4 → 5/2 | note:G3 ]",
+  "[ 5/2 → 11/4 | note:Eb3 ]",
+  "[ 11/4 → 3/1 | note:Bb3 ]",
+  "[ 3/1 → 13/4 | note:C3 ]",
+  "[ 13/4 → 7/2 | note:D3 ]",
+  "[ 7/2 → 15/4 | note:G3 ]",
+  "[ 15/4 → 4/1 | note:Eb3 ]",
+]
+`;
+
 exports[`runs examples > example "room" example index 0 1`] = `
 [
   "[ 0/1 → 1/2 | s:bd room:0 ]",

website/src/pages/learn/notes.mdx

@@ -9,7 +9,7 @@ import { JsDoc } from '../../docs/JsDoc';
 
 # Notes
 
-Pitches are an essential building block for music.
+Pitches are an important building block in many musical traditions.
 In Strudel, pitches can be expressed as note names, note numbers or frequencies.
 Here's the same pattern written in three different ways:
 

website/src/pages/learn/time-modifiers.mdx

@@ -101,3 +101,7 @@ Some of these have equivalent operators in the Mini Notation:
 ## cpm
 
 <JsDoc client:idle name="cpm" h={0} />
+
+## ribbon
+
+<JsDoc client:idle name="ribbon" h={0} />