Merge commit '5f381cf1536e3c87e16cf164e91666d8b7ec403a' into voicing-rework

2026-07-27 15:29:18 -04:00 · 2022-10-27 22:36:34 +02:00
parent d323b6843d 5f381cf153
commit d23085e553
14 changed files with 2965 additions and 11070 deletions
@@ -62,12 +62,12 @@ const generic_params = [
   */
  ['f', 'accelerate', 'a pattern of numbers that speed up (or slow down) samples while they play.'],
  /**
-   * Like {@link amp}, but exponential.
+   * Controls the gain by an exponential amount.
   *
   * @name gain
   * @param {number | Pattern} amount gain.
   * @example
-   * s("bd*8").gain(".7*2 1 .7*2 1 .7 1").osc()
+   * s("hh*8").gain(".4!2 1 .4!2 1 .4 1").out()
   *
   */
  [
@@ -147,10 +147,12 @@ const generic_params = [
  /**
   * a pattern of numbers from 0 to 1. Skips the beginning of each sample, e.g. `0.25` to cut off the first quarter from each sample.
   *
+   * @memberof Pattern
   * @name begin
   * @param {number | Pattern} amount between 0 and 1, where 1 is the length of the sample
   * @example
-   * s("rave").begin("<0 .25 .5 .75>").osc()
+   * samples({ rave: 'rave/AREUREADY.wav' }, 'github:tidalcycles/Dirt-Samples/master/')
+   * s("rave").begin("<0 .25 .5 .75>").out()
   *
   */
  [
@@ -159,12 +161,13 @@ const generic_params = [
    'a pattern of numbers from 0 to 1. Skips the beginning of each sample, e.g. `0.25` to cut off the first quarter from each sample.',
  ],
  /**
-   * The same as {@link begin}, but cuts off the end off each sample.
+   * The same as .begin, but cuts off the end off each sample.
   *
+   * @memberof Pattern
   * @name end
   * @param {number | Pattern} length 1 = whole sample, .5 = half sample, .25 = quarter sample etc..
   * @example
-   * s("bd*2,ho*4").end("<.1 .2 .5 1>").osc()
+   * s("bd*2,ho*4").end("<.1 .2 .5 1>").out()
   *
   */
  [
@@ -25,14 +25,19 @@ const euclid = (pulses, steps, rotation = 0) => {
 * describe a large number of rhythms used in the most important music world traditions.
 *
 * @memberof Pattern
+ * @name euclid
 * @param {number} pulses the number of onsets / beats
 * @param {number} steps the number of steps to fill
 * @param {number} rotation (optional) offset in steps
 * @returns Pattern
- * @example // The Cuban tresillo pattern.
- * "c3".euclid(3,8)
+ * @example
+ * // The Cuban tresillo pattern.
+ * n("c3").euclid(3,8).out()
+ */
+
+/**
 * @example // A thirteenth century Persian rhythm called Khafif-e-ramal.
- * "c3".euclid(2,5)
+ * n("c3").euclid(2,5)
 * @example // The archetypal pattern of the Cumbia from Colombia, as well as a Calypso rhythm from Trinidad.
 * "c3".euclid(3,4)
 * @example // Another thirteenth century Persian rhythm by the name of Khafif-e-ramal, as well as a Rumanian folk-dance rhythm.
@@ -79,7 +84,11 @@ Pattern.prototype.euclid = function (pulses, steps, rotation = 0) {
 };

 /**
- * Similar to {@link Pattern#euclid}, but each pulse is held until the next pulse, so there will be no gaps.
+ * Similar to `.euclid`, but each pulse is held until the next pulse, so there will be no gaps.
+ * @name euclidLegato
+ * @memberof Pattern
+ * @example
+ * n("g2").decay(.1).sustain(.3).euclidLegato(3,8).out()
 */
 Pattern.prototype.euclidLegato = function (pulses, steps, rotation = 0) {
  const bin_pat = euclid(pulses, steps, rotation);
@@ -468,7 +468,11 @@ export class Pattern {
  /**
   * Assumes a numerical pattern. Returns a new pattern with all values rounded
   * to the nearest integer.
+   * @name round
+   * @memberof Pattern
   * @returns Pattern
+   * @example
+   * "0.5 1.5 2.5".round().scale('C major')
   */
  round() {
    return this._asNumber().fmap((v) => Math.round(v));
@@ -522,7 +526,7 @@ export class Pattern {
   * @example
   * s("bd sd,hh*4").cutoff(sine.range(500,2000).slow(4)).out()
   */
-  range(min, max) {
+  _range(min, max) {
    return this.mul(max - min).add(min);
  }

@@ -534,8 +538,8 @@ export class Pattern {
   * @param {Number} max
   * @returns Pattern
   */
-  rangex(min, max) {
-    return this.range(Math.log(min), Math.log(max)).fmap(Math.exp);
+  _rangex(min, max) {
+    return this._range(Math.log(min), Math.log(max)).fmap(Math.exp);
  }

  /**
@@ -545,8 +549,8 @@ export class Pattern {
   * @param {Number} max
   * @returns Pattern
   */
-  range2(min, max) {
-    return this._fromBipolar().range(min, max);
+  _range2(min, max) {
+    return this._fromBipolar()._range(min, max);
  }

  _bindWhole(choose_whole, func) {
@@ -695,6 +699,13 @@ export class Pattern {
    return this.fmap(func)._squeezeJoin();
  }

+  /**
+   * Like layer, but with a single function:
+   * @name apply
+   * @memberof Pattern
+   * @example
+   * "<c3 eb3 g3>".scale('C minor').apply(scaleTranspose("0,2,4"))
+   */
  _apply(func) {
    return func(this);
  }
@@ -739,13 +750,20 @@ export class Pattern {
      const end = cycle.add(span.end.sub(cycle).mul(factor).min(1));
      return new TimeSpan(begin, end);
    };
-    const ef = function (span) {
-      const cycle = span.begin.sam();
-      const begin = cycle.add(span.begin.sub(cycle).div(factor).min(1));
-      const end = cycle.add(span.end.sub(cycle).div(factor).min(1));
-      return new TimeSpan(begin, end);
+    const ef = function (hap) {
+      const begin = hap.part.begin;
+      const end = hap.part.end;
+      const cycle = begin.sam();
+      const beginPos = begin.sub(cycle).div(factor).min(1);
+      const endPos = end.sub(cycle).div(factor).min(1);
+      const newPart = new TimeSpan(cycle.add(beginPos), cycle.add(endPos))
+      const newWhole = !hap.whole ? undefined : new TimeSpan(
+        newPart.begin.sub(begin.sub(hap.whole.begin).div(factor)),
+        newPart.end.add(hap.whole.end.sub(end).div(factor))
+      );
+      return new Hap(newWhole, newPart, hap.value, hap.context);
    };
-    return this.withQuerySpan(qf).withHapSpan(ef)._splitQueries();
+    return this.withQuerySpan(qf)._withHap(ef)._splitQueries();
  }

  // Compress each cycle into the given timespan, leaving a gap
@@ -765,7 +783,7 @@ export class Pattern {
  _focus(b, e) {
    return this._fast(Fraction(1).div(e.sub(b))).late(b.cyclePos());
  }
-    
+
  _focusSpan(span) {
    return this._focus(span.begin, span.end);
  }
@@ -811,6 +829,20 @@ export class Pattern {
    return this.fmap((x) => pure(x)._fast(factor))._squeezeJoin();
  }

+  /**
+   * Cuts each sample into the given number of parts, allowing you to explore a technique known as 'granular synthesis'.
+   * It turns a pattern of samples into a pattern of parts of samples.
+   * @name chop
+   * @memberof Pattern
+   * @returns Pattern
+   * @example
+   * samples({ rhodes: 'https://cdn.freesound.org/previews/132/132051_316502-lq.mp3' })
+   * s("rhodes")
+   *  .chop(4)
+   *  .rev() // reverse order of chops
+   *  .loopAt(4,1) // fit sample into 4 cycles
+   *  .out()
+   */
  _chop(n) {
    const slices = Array.from({ length: n }, (x, i) => i);
    const slice_objects = slices.map((i) => ({ begin: i / n, end: (i + 1) / n }));
@@ -1182,6 +1214,9 @@ export class Pattern {
   * @name echo
   * @memberof Pattern
   * @returns Pattern
+   * @param {number} times how many times to repeat
+   * @param {number} time cycle offset between iterations
+   * @param {number} feedback velocity multiplicator for each iteration
   * @example
   * s("bd sd").echo(3, 1/6, .8).out()
   */
@@ -1254,16 +1289,40 @@ export class Pattern {
    return this.withHapSpan((span) => new TimeSpan(span.begin, span.begin.add(value)));
  }

-  // sets hap relative duration of haps
+  /**
+   *
+   * Multiplies the hap duration with the given factor.
+   * @name legato
+   * @memberof Pattern
+   * @example
+   * n("c3 eb3 g3 c4").legato("<.25 .5 1 2>").out()
+   */
  _legato(value) {
    return this.withHapSpan((span) => new TimeSpan(span.begin, span.begin.add(span.end.sub(span.begin).mul(value))));
  }

+  /**
+   *
+   * Sets the velocity from 0 to 1. Is multiplied together with gain.
+   * @name velocity
+   * @example
+   * s("hh*8")
+   * .gain(".4!2 1 .4!2 1 .4 1")
+   * .velocity(".4 1").out()
+   */
  _velocity(velocity) {
    return this._withContext((context) => ({ ...context, velocity: (context.velocity || 1) * velocity }));
  }

-  // move this to controls? (speed and unit are controls)
+  /**
+   * Makes the sample fit the given number of cycles by changing the speed.
+   * @name loopAt
+   * @memberof Pattern
+   * @returns Pattern
+   * @example
+   * samples({ rhodes: 'https://cdn.freesound.org/previews/132/132051_316502-lq.mp3' })
+   * s("rhodes").loopAt(4,1).out()
+   */
  _loopAt(factor, cps = 1) {
    return this.speed((1 / factor) * cps)
      .unit('c')
@@ -1319,9 +1378,48 @@ function _composeOp(a, b, func) {
    keepif: [(a, b) => (b ? a : undefined)],

    // numerical functions
+    /**
+     *
+     * Assumes a pattern of numbers. Adds the given number to each item in the pattern.
+     * @name add
+     * @memberof Pattern
+     * @example
+     * // Here, the triad 0, 2, 4 is shifted by different amounts
+     * "0 2 4".add("<0 3 4 0>").scale('C major')
+     * // Without add, the equivalent would be:
+     * // "<[0 2 4] [3 5 7] [4 6 8] [0 2 4]>".scale('C major')
+     * @example
+     * // You can also use add with notes:
+     * "c3 e3 g3".add("<0 5 7 0>")
+     * // Behind the scenes, the notes are converted to midi numbers:
+     * // "48 52 55".add("<0 5 7 0>")
+     */
    add: [(a, b) => a + b, numOrString], // support string concatenation
+    /**
+     *
+     * Like add, but the given numbers are subtracted.
+     * @name sub
+     * @memberof Pattern
+     * @example
+     * "0 2 4".sub("<0 1 2 3>").scale('C4 minor')
+     * // See add for more information.
+     */
    sub: [(a, b) => a - b, num],
+    /**
+     *
+     * Multiplies each number by the given factor.
+     * @name mul
+     * @memberof Pattern
+     * @example
+     * "1 1.5 [1.66, <2 2.33>]".mul(150).freq().out()
+     */
    mul: [(a, b) => a * b, num],
+    /**
+     *
+     * Divides each number by the given factor.
+     * @name div
+     * @memberof Pattern
+     */
    div: [(a, b) => a / b, num],
    mod: [mod, num],
    pow: [Math.pow, num],
@@ -1363,8 +1461,7 @@ function _composeOp(a, b, func) {
          // avoid union, as we want to throw away the value of 'b' completely
          result = pat['_op' + how](other, (a) => (b) => op(a, b));
          result = result._removeUndefineds();
-        }
-        else {
+        } else {
          result = pat['_op' + how](other, (a) => (b) => _composeOp(a, b, op));
        }
        return result;
@@ -1657,6 +1754,7 @@ export const mul = curry((a, pat) => pat.mul(a));
 export const off = curry((t, f, pat) => pat.off(t, f));
 export const ply = curry((a, pat) => pat.ply(a));
 export const range = curry((a, b, pat) => pat.range(a, b));
+export const rangex = curry((a, b, pat) => pat.rangex(a, b));
 export const range2 = curry((a, b, pat) => pat.range2(a, b));
 export const rev = (pat) => pat.rev();
 export const slow = curry((a, pat) => pat.slow(a));
@@ -1743,6 +1841,18 @@ Pattern.prototype.inside = function (...args) {
  args = args.map(reify);
  return patternify2(Pattern.prototype._inside)(...args, this);
 };
+Pattern.prototype.range = function (...args) {
+  args = args.map(reify);
+  return patternify2(Pattern.prototype._range)(...args, this);
+};
+Pattern.prototype.rangex = function (...args) {
+  args = args.map(reify);
+  return patternify2(Pattern.prototype._rangex)(...args, this);
+};
+Pattern.prototype.range2 = function (...args) {
+  args = args.map(reify);
+  return patternify2(Pattern.prototype._range2)(...args, this);
+};

 // call this after all Patter.prototype.define calls have been executed! (right before evaluate)
 Pattern.prototype.bootstrap = function () {
@@ -372,6 +372,11 @@ describe('Pattern', () => {
        sequence(['a', 'b', 'c'], silence, ['a', 'b', 'c'], silence).firstCycle(),
      );
    });
+    it('copes with breaking up events across cycles', () => {
+      expect(pure('a').slow(2)._fastGap(2)._setContext({}).query(st(0, 2))).toStrictEqual(
+        [hap(ts(0, 1), ts(0, 0.5), 'a'), hap(ts(0.5, 1.5), ts(1, 1.5), 'a')]
+      );
+    });
  });
  describe('_compressSpan()', () => {
    it('Can squash cycles of a pattern into a given timespan', () => {
@@ -848,6 +853,13 @@ describe('Pattern', () => {
      );
    });
  });
+  describe('range', () => {
+    it('Can be patterned', () => {
+      expect(sequence(0, 0).range(sequence(0, 0.5), 1).firstCycle()).toStrictEqual(
+        sequence(0, 0.5).firstCycle(),
+      );
+    });
+  });
  describe('range2', () => {
    it('Can change the range of a bipolar pattern', () => {
      expect(sequence(-1, -0.5, 0, 0.5).range2(1000, 1100).firstCycle()).toStrictEqual(
@@ -1,11 +1,11 @@
 /*
-util.test.mjs - <short description TODO>
+util.test.mjs - Tests for the core 'util' module
 Copyright (C) 2022 Strudel contributors - see <https://github.com/tidalcycles/strudel/blob/main/packages/core/test/util.test.mjs>
 This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */

 import { pure } from '../pattern.mjs';
-import { isNote, tokenizeNote, toMidi, fromMidi, mod, compose, getFrequency } from '../util.mjs';
+import { isNote, tokenizeNote, toMidi, fromMidi, mod, compose, getFrequency, getPlayableNoteValue } from '../util.mjs';
 import { describe, it, expect } from 'vitest';

 describe('isNote', () => {
@@ -70,6 +70,10 @@ describe('toMidi', () => {
    expect(toMidi('C#3')).toEqual(49);
    expect(toMidi('C##3')).toEqual(50);
  });
+  it('should throw an error when given a non-note', () => {
+    expect(() => toMidi('Q')).toThrowError(`not a note: "Q"`);
+    expect(() => toMidi('Z')).toThrowError(`not a note: "Z"`);
+  });
 });
 describe('fromMidi', () => {
  it('should turn midi into frequency', () => {
@@ -78,13 +82,27 @@ describe('fromMidi', () => {
  });
 });
 describe('getFrequency', () => {
-  it('should turn midi into frequency', () => {
-    const happify = (val, context = {}) => pure(val).firstCycle()[0].setContext(context);
+  const happify = (val, context = {}) => pure(val).firstCycle()[0].setContext(context);
+  it('should turn note into frequency', () => {
    expect(getFrequency(happify('a4'))).toEqual(440);
    expect(getFrequency(happify('a3'))).toEqual(220);
-    expect(getFrequency(happify(440, { type: 'frequency' }))).toEqual(440); // TODO: migrate when values are objects..
+  });
+  it('should turn midi into frequency', () => {
+    expect(getFrequency(happify(69, { type: 'midi' }))).toEqual(440);
+    expect(getFrequency(happify(57, { type: 'midi' }))).toEqual(220);
+  });
+  it('should return frequencies unchanged', () => {
+    expect(getFrequency(happify(440, { type: 'frequency' }))).toEqual(440); 
    expect(getFrequency(happify(432, { type: 'frequency' }))).toEqual(432);
  });
+  it('should turn object with a "freq" property into frequency', () => {
+    expect(getFrequency(happify({freq: 220}))).toEqual(220)
+    expect(getFrequency(happify({freq: 440}))).toEqual(440)
+  });
+  it('should throw an error when given a non-note', () => {
+    expect(() => getFrequency(happify('Q'))).toThrowError(`not a note or frequency: Q`)
+    expect(() => getFrequency(happify('Z'))).toThrowError(`not a note or frequency: Z`)
+  });
 });

 describe('mod', () => {
@@ -118,3 +136,26 @@ describe('compose', () => {
    expect(compose(addS('a'), addS('b'))('x')).toEqual('xab');
  });
 });
+
+describe('getPlayableNoteValue', () => {
+  const happify = (val, context = {}) => pure(val).firstCycle()[0].setContext(context);
+  it('should return object "note" property', () => {
+    expect(getPlayableNoteValue(happify({note: "a4"}))).toEqual('a4')
+  });
+  it('should return object "n" property', () => {
+    expect(getPlayableNoteValue(happify({n: "a4"}))).toEqual('a4')
+  });
+  it('should return object "value" property', () => {
+    expect(getPlayableNoteValue(happify({value: "a4"}))).toEqual('a4')
+  });
+  it('should turn midi into frequency', () => {
+    expect(getPlayableNoteValue(happify(57, {type: 'midi'}))).toEqual(220)
+  })
+  it('should return frequency value', () => {
+    expect(getPlayableNoteValue(happify(220, {type: 'frequency'}))).toEqual(220)
+  })
+  it('should throw an error if value is not an object, number, or string', () => {
+    expect(() => getPlayableNoteValue(happify(false))).toThrowError(`not a note: false`)
+    expect(() => getPlayableNoteValue(happify(undefined))).toThrowError(`not a note: undefined`)
+  })
+});
@@ -31,6 +31,9 @@ export const fromMidi = (n) => {
  return Math.pow(2, (n - 69) / 12) * 440;
 };

+/**
+ * @deprecated does not appear to be referenced or invoked anywhere in the codebase
+ */
 export const getFreq = (noteOrMidi) => {
  if (typeof noteOrMidi === 'number') {
    return fromMidi(noteOrMidi);
@@ -38,6 +41,9 @@ export const getFreq = (noteOrMidi) => {
  return fromMidi(toMidi(noteOrMidi));
 };

+/**
+ * @deprecated does not appear to be referenced or invoked anywhere in the codebase
+ */
 export const midi2note = (n) => {
  const oct = Math.floor(n / 12) - 1;
  const pc = ['C', 'Db', 'D', 'Eb', 'E', 'F', 'Gb', 'G', 'Ab', 'A', 'Bb', 'B'][n % 12];
@@ -75,7 +81,7 @@ export const getFrequency = (hap) => {
  } else if (typeof value === 'string' && isNote(value)) {
    value = fromMidi(toMidi(hap.value));
  } else if (typeof value !== 'number') {
-    throw new Error('not a note or frequency:' + value);
+    throw new Error('not a note or frequency: ' + value);
  }
  return value;
 };
@@ -18,3 +18,6 @@ if (typeof AudioContext !== 'undefined') {
    return convolver;
  };
 }
+
+// TODO: make the reverb more exciting
+// check out https://blog.gskinner.com/archives/2019/02/reverb-web-audio-api.html