support sample stretching

src/classes/SoundEvent.ts

@@ -295,6 +295,13 @@ export class SoundEvent extends AudibleEvent {
   public size = (value: number) => this.updateValue("size", value);
   public sz = this.size;
 
+  // Unit
+  public stretch = (beat: number) => {
+    this.updateValue("unit", "c");
+    this.updateValue("speed", 2 / beat)
+    return this;
+  }
+
   // ================================================================================
   // AbstactEvent overrides
   // ================================================================================

src/documentation/engine.ts

@@ -188,6 +188,7 @@ There are some basic controls over the playback of each sample. This allows you
 | loopBegin |     | Beginning of the loop section (between <ic>0</ic> and <ic>1</ic>)        |
 | loopEnd |     | End of the loop section (between <ic>0</ic> and <ic>1</ic>)        |
 | loop    |       | Whether to loop or not the audio sample          |
+| stretch    |       | Stretches the audio playback rate of a sample over <ic>n</ic> beats          |
 | speed   |       | Playback speed (<ic>2</ic> = twice as fast)         |
 | cut     |       | Set with <ic>0</ic> or <ic>1</ic>. Will cut the sample as soon as another sample is played on the same bus |
 | clip    |       | Multiply the duration of the sample with the given number |
@@ -207,6 +208,15 @@ beat(.5)::snd('pad').begin(0.2)
     true
   )};
 	
+${makeExample(
+    "Playing an amen break",
+    `
+// Note that stretch has the same value as beat
+beat(4) :: sound('breaks165').stretch(4).out()
+beat(0.25) :: sound('hh').out()
+beat(1, 4, 8) :: sound('bd').out()`,
+    true,
+  )};
 	
 ## Filters