hacklab/strudel
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Annote pattern.mjs and signal.mjs

Browse source
This commit is contained in:
Václav Volhejn 2025-10-01 23:45:48 +02:00
parent c754dab1ef
commit 4a395f372d
4 changed files with 198 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

1
jsdoc/jsdoc-synonyms.js
View file

@ -17,7 +17,6 @@ function defineTags(dictionary) {
mustHaveValue: true, mustHaveValue: true,
onTagged: function (doclet, tag) { onTagged: function (doclet, tag) {
doclet.group = tag.value; doclet.group = tag.value;
console.log('TAGGED GROUP:', doclet.group);
}, },
}); });
} }

146
packages/core/pattern.mjs
View file

@ -84,6 +84,7 @@ export class Pattern {
/** /**
* Returns a new pattern, with the function applied to the value of * Returns a new pattern, with the function applied to the value of
* each hap. It has the alias `fmap`. * each hap. It has the alias `fmap`.
* @group functional
* @synonyms fmap * @synonyms fmap
* @param {Function} func to to apply to the value * @param {Function} func to to apply to the value
* @returns Pattern * @returns Pattern
@ -116,6 +117,7 @@ export class Pattern {
* Assumes 'this' is a pattern of functions, and given a function to * Assumes 'this' is a pattern of functions, and given a function to
* resolve wholes, applies a given pattern of values to that * resolve wholes, applies a given pattern of values to that
* pattern of functions. * pattern of functions.
* @group functional
* @param {Function} whole_func * @param {Function} whole_func
* @param {Function} func * @param {Function} func
* @noAutocomplete * @noAutocomplete
@ -153,6 +155,7 @@ export class Pattern {
* In this `_appBoth` variant, where timespans of the function and value haps * In this `_appBoth` variant, where timespans of the function and value haps
* are not the same but do intersect, the resulting hap has a timespan of the * are not the same but do intersect, the resulting hap has a timespan of the
* intersection. This applies to both the part and the whole timespan. * intersection. This applies to both the part and the whole timespan.
* @group functional
* @param {Pattern} pat_val * @param {Pattern} pat_val
* @noAutocomplete * @noAutocomplete
* @returns Pattern * @returns Pattern
@ -180,6 +183,7 @@ export class Pattern {
* on. In practice, this means that the pattern structure, including onsets, * on. In practice, this means that the pattern structure, including onsets,
* are preserved from the pattern of functions (often referred to as the left * are preserved from the pattern of functions (often referred to as the left
* hand or inner pattern). * hand or inner pattern).
* @group functional
* @param {Pattern} pat_val * @param {Pattern} pat_val
* @noAutocomplete * @noAutocomplete
* @returns Pattern * @returns Pattern
@ -213,6 +217,7 @@ export class Pattern {
* As with `appLeft`, but `whole` timespans are instead taken from the * As with `appLeft`, but `whole` timespans are instead taken from the
* pattern of values, i.e. structure is preserved from the right hand/outer * pattern of values, i.e. structure is preserved from the right hand/outer
* pattern. * pattern.
* @group functional
* @param {Pattern} pat_val * @param {Pattern} pat_val
* @noAutocomplete * @noAutocomplete
* @returns Pattern * @returns Pattern
@ -403,6 +408,7 @@ export class Pattern {
/** /**
* Query haps inside the given time span. * Query haps inside the given time span.
* *
* @group internals
* @param {Fraction | number} begin from time * @param {Fraction | number} begin from time
* @param {Fraction | number} end to time * @param {Fraction | number} end to time
* @returns Hap[] * @returns Hap[]
@ -426,6 +432,7 @@ export class Pattern {
* Returns a new pattern, with queries split at cycle boundaries. This makes * Returns a new pattern, with queries split at cycle boundaries. This makes
* some calculations easier to express, as all haps are then constrained to * some calculations easier to express, as all haps are then constrained to
* happen within a cycle. * happen within a cycle.
* @group internals
* @returns Pattern * @returns Pattern
* @noAutocomplete * @noAutocomplete
*/ */
@ -440,6 +447,7 @@ export class Pattern {
/** /**
* Returns a new pattern, where the given function is applied to the query * Returns a new pattern, where the given function is applied to the query
* timespan before passing it to the original pattern. * timespan before passing it to the original pattern.
* @group internals
* @param {Function} func the function to apply * @param {Function} func the function to apply
* @returns Pattern * @returns Pattern
* @noAutocomplete * @noAutocomplete
@ -462,6 +470,7 @@ export class Pattern {
/** /**
* As with `withQuerySpan`, but the function is applied to both the * As with `withQuerySpan`, but the function is applied to both the
* begin and end time of the query timespan. * begin and end time of the query timespan.
* @group internals
* @param {Function} func the function to apply * @param {Function} func the function to apply
* @returns Pattern * @returns Pattern
* @noAutocomplete * @noAutocomplete
@ -474,6 +483,7 @@ export class Pattern {
* Similar to `withQuerySpan`, but the function is applied to the timespans * Similar to `withQuerySpan`, but the function is applied to the timespans
* of all haps returned by pattern queries (both `part` timespans, and where * of all haps returned by pattern queries (both `part` timespans, and where
* present, `whole` timespans). * present, `whole` timespans).
* @group internals
* @param {Function} func * @param {Function} func
* @returns Pattern * @returns Pattern
* @noAutocomplete * @noAutocomplete
@ -485,6 +495,7 @@ export class Pattern {
/** /**
* As with `withHapSpan`, but the function is applied to both the * As with `withHapSpan`, but the function is applied to both the
* begin and end time of the hap timespans. * begin and end time of the hap timespans.
* @group internals
* @param {Function} func the function to apply * @param {Function} func the function to apply
* @returns Pattern * @returns Pattern
* @noAutocomplete * @noAutocomplete
@ -495,6 +506,7 @@ export class Pattern {
/** /**
* Returns a new pattern with the given function applied to the list of haps returned by every query. * Returns a new pattern with the given function applied to the list of haps returned by every query.
* @group internals
* @param {Function} func * @param {Function} func
* @returns Pattern * @returns Pattern
* @noAutocomplete * @noAutocomplete
@ -507,6 +519,7 @@ export class Pattern {
/** /**
* As with `withHaps`, but applies the function to every hap, rather than every list of haps. * As with `withHaps`, but applies the function to every hap, rather than every list of haps.
* @group internals
* @param {Function} func * @param {Function} func
* @returns Pattern * @returns Pattern
* @noAutocomplete * @noAutocomplete
@ -517,6 +530,7 @@ export class Pattern {
/** /**
* Returns a new pattern with the context field set to every hap set to the given value. * Returns a new pattern with the context field set to every hap set to the given value.
* @group internals
* @param {*} context * @param {*} context
* @returns Pattern * @returns Pattern
* @noAutocomplete * @noAutocomplete
@ -527,6 +541,7 @@ export class Pattern {
/** /**
* Returns a new pattern with the given function applied to the context field of every hap. * Returns a new pattern with the given function applied to the context field of every hap.
* @group internals
* @param {Function} func * @param {Function} func
* @returns Pattern * @returns Pattern
* @noAutocomplete * @noAutocomplete
@ -542,6 +557,7 @@ export class Pattern {
/** /**
* Returns a new pattern with the context field of every hap set to an empty object. * Returns a new pattern with the context field of every hap set to an empty object.
* @group internals
* @returns Pattern * @returns Pattern
* @noAutocomplete * @noAutocomplete
*/ */
@ -552,6 +568,7 @@ export class Pattern {
/** /**
* Returns a new pattern with the given location information added to the * Returns a new pattern with the given location information added to the
* context of every hap. * context of every hap.
* @group internals
* @param {Number} start start offset * @param {Number} start start offset
* @param {Number} end end offset * @param {Number} end end offset
* @returns Pattern * @returns Pattern
@ -575,6 +592,7 @@ export class Pattern {
/** /**
* Returns a new Pattern, which only returns haps that meet the given test. * Returns a new Pattern, which only returns haps that meet the given test.
* @group internals
* @param {Function} hap_test - a function which returns false for haps to be removed from the pattern * @param {Function} hap_test - a function which returns false for haps to be removed from the pattern
* @returns Pattern * @returns Pattern
* @noAutocomplete * @noAutocomplete
@ -586,6 +604,7 @@ export class Pattern {
/** /**
* As with `filterHaps`, but the function is applied to values * As with `filterHaps`, but the function is applied to values
* inside haps. * inside haps.
* @group internals
* @param {Function} value_test * @param {Function} value_test
* @returns Pattern * @returns Pattern
* @noAutocomplete * @noAutocomplete
@ -597,6 +616,7 @@ export class Pattern {
/** /**
* Returns a new pattern, with haps containing undefined values removed from * Returns a new pattern, with haps containing undefined values removed from
* query results. * query results.
* @group internals
* @returns Pattern * @returns Pattern
* @noAutocomplete * @noAutocomplete
*/ */
@ -608,6 +628,7 @@ export class Pattern {
* Returns a new pattern, with all haps without onsets filtered out. A hap * Returns a new pattern, with all haps without onsets filtered out. A hap
* with an onset is one with a `whole` timespan that begins at the same time * with an onset is one with a `whole` timespan that begins at the same time
* as its `part` timespan. * as its `part` timespan.
* @group internals
* @returns Pattern * @returns Pattern
* @noAutocomplete * @noAutocomplete
*/ */
@ -621,6 +642,7 @@ export class Pattern {
/** /**
* Returns a new pattern, with 'continuous' haps (those without 'whole' * Returns a new pattern, with 'continuous' haps (those without 'whole'
* timespans) removed from query results. * timespans) removed from query results.
* @group internals
* @returns Pattern * @returns Pattern
* @noAutocomplete * @noAutocomplete
*/ */
@ -632,6 +654,7 @@ export class Pattern {
/** /**
* Combines adjacent haps with the same value and whole. Only * Combines adjacent haps with the same value and whole. Only
* intended for use in tests. * intended for use in tests.
* @group internals
* @noAutocomplete * @noAutocomplete
*/ */
defragmentHaps() { defragmentHaps() {
@ -684,6 +707,7 @@ export class Pattern {
/** /**
* Queries the pattern for the first cycle, returning Haps. Mainly of use when * Queries the pattern for the first cycle, returning Haps. Mainly of use when
* debugging a pattern. * debugging a pattern.
* @group internals
* @param {Boolean} with_context - set to true, otherwise the context field * @param {Boolean} with_context - set to true, otherwise the context field
* will be stripped from the resulting haps. * will be stripped from the resulting haps.
* @returns [Hap] * @returns [Hap]
@ -699,6 +723,7 @@ export class Pattern {
/** /**
* Accessor for a list of values returned by querying the first cycle. * Accessor for a list of values returned by querying the first cycle.
* @group internals
* @noAutocomplete * @noAutocomplete
*/ */
get firstCycleValues() { get firstCycleValues() {
@ -707,6 +732,7 @@ export class Pattern {
/** /**
* More human-readable version of the `firstCycleValues` accessor. * More human-readable version of the `firstCycleValues` accessor.
* @group internals
* @noAutocomplete * @noAutocomplete
*/ */
get showFirstCycle() { get showFirstCycle() {
@ -718,6 +744,7 @@ export class Pattern {
/** /**
* Returns a new pattern, which returns haps sorted in temporal order. Mainly * Returns a new pattern, which returns haps sorted in temporal order. Mainly
* of use when comparing two patterns for equality, in tests. * of use when comparing two patterns for equality, in tests.
* @group internals
* @returns Pattern * @returns Pattern
* @noAutocomplete * @noAutocomplete
*/ */
@ -732,6 +759,10 @@ export class Pattern {
); );
} }
/**
* Returns a new pattern with all values parsed as numerals.
* @group internals
*/
asNumber() { asNumber() {
return this.fmap(parseNumeral); return this.fmap(parseNumeral);
} }
@ -782,6 +813,7 @@ export class Pattern {
/** /**
* Layers the result of the given function(s). Like `superimpose`, but without the original pattern: * Layers the result of the given function(s). Like `superimpose`, but without the original pattern:
* @name layer * @name layer
* @group combiners
* @memberof Pattern * @memberof Pattern
* @synonyms apply * @synonyms apply
* @returns Pattern * @returns Pattern
@ -797,6 +829,7 @@ export class Pattern {
/** /**
* Superimposes the result of the given function(s) on top of the original pattern: * Superimposes the result of the given function(s) on top of the original pattern:
* @name superimpose * @name superimpose
* @group combiners
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
* @example * @example
@ -856,6 +889,7 @@ export class Pattern {
/** /**
* Writes the content of the current event to the console (visible in the side menu). * Writes the content of the current event to the console (visible in the side menu).
* @group visualizers
* @name log * @name log
* @memberof Pattern * @memberof Pattern
* @example * @example
@ -870,6 +904,7 @@ export class Pattern {
/** /**
* A simplified version of `log` which writes all "values" (various configurable parameters) * A simplified version of `log` which writes all "values" (various configurable parameters)
* within the event to the console (visible in the side menu). * within the event to the console (visible in the side menu).
* @group visualizers
* @name logValues * @name logValues
* @memberof Pattern * @memberof Pattern
* @example * @example
@ -903,6 +938,7 @@ export class Pattern {
* source pattern to be looped, and for an (optional) given function to be * source pattern to be looped, and for an (optional) given function to be
* applied. False values result in the corresponding part of the source pattern * applied. False values result in the corresponding part of the source pattern
* to be played unchanged. * to be played unchanged.
* @group structure
* @name into * @name into
* @memberof Pattern * @memberof Pattern
* @example * @example
@ -942,6 +978,7 @@ Pattern.prototype.collect = function () {
/** /**
* Selects indices in in stacked notes. * Selects indices in in stacked notes.
* @group transforms
* @example * @example
* note("<[c,eb,g]!2 [c,f,ab] [d,f,ab]>") * note("<[c,eb,g]!2 [c,f,ab] [d,f,ab]>")
* .arpWith(haps => haps[2]) * .arpWith(haps => haps[2])
@ -956,6 +993,7 @@ export const arpWith = register('arpWith', (func, pat) => {
/** /**
* Selects indices in in stacked notes. * Selects indices in in stacked notes.
* @group transforms
* @example * @example
* note("<[c,eb,g]!2 [c,f,ab] [d,f,ab]>") * note("<[c,eb,g]!2 [c,f,ab] [d,f,ab]>")
* .arp("0 [0,2] 1 [0,2]") * .arp("0 [0,2] 1 [0,2]")
@ -1038,6 +1076,7 @@ function _composeOp(a, b, func) {
* note("c3 e3 g3".add("<0 5 7 0>")) * note("c3 e3 g3".add("<0 5 7 0>"))
* // Behind the scenes, the notes are converted to midi numbers: * // Behind the scenes, the notes are converted to midi numbers:
* // note("48 52 55".add("<0 5 7 0>")) * // note("48 52 55".add("<0 5 7 0>"))
* @group transforms
*/ */
add: [numeralArgs((a, b) => a + b)], // support string concatenation add: [numeralArgs((a, b) => a + b)], // support string concatenation
/** /**
@ -1150,6 +1189,7 @@ function _composeOp(a, b, func) {
/** /**
* Applies the given structure to the pattern: * Applies the given structure to the pattern:
* *
* @group structure
* @example * @example
* note("c,eb,g") * note("c,eb,g")
* .struct("x ~ x ~ ~ x ~ x ~ ~ ~ x ~ x ~ ~") * .struct("x ~ x ~ ~ x ~ x ~ ~ ~ x ~ x ~ ~")
@ -1164,6 +1204,7 @@ function _composeOp(a, b, func) {
/** /**
* Returns silence when mask is 0 or "~" * Returns silence when mask is 0 or "~"
* *
* @group structure
* @example * @example
* note("c [eb,g] d [eb,g]").mask("<1 [0 1]>") * note("c [eb,g] d [eb,g]").mask("<1 [0 1]>")
*/ */
@ -1176,6 +1217,7 @@ function _composeOp(a, b, func) {
/** /**
* Resets the pattern to the start of the cycle for each onset of the reset pattern. * Resets the pattern to the start of the cycle for each onset of the reset pattern.
* *
* @group structure
* @example * @example
* s("[<bd lt> sd]*2, hh*8").reset("<x@3 x(5,8)>") * s("[<bd lt> sd]*2, hh*8").reset("<x@3 x(5,8)>")
*/ */
@ -1189,6 +1231,7 @@ function _composeOp(a, b, func) {
* Restarts the pattern for each onset of the restart pattern. * Restarts the pattern for each onset of the restart pattern.
* While reset will only reset the current cycle, restart will start from cycle 0. * While reset will only reset the current cycle, restart will start from cycle 0.
* *
* @group structure
* @example * @example
* s("[<bd lt> sd]*2, hh*8").restart("<x@3 x(5,8)>") * s("[<bd lt> sd]*2, hh*8").restart("<x@3 x(5,8)>")
*/ */
@ -1229,6 +1272,7 @@ export const pm = polymeter;
/** /**
* Does absolutely nothing, but with a given metrical 'steps' * Does absolutely nothing, but with a given metrical 'steps'
* @name gap * @name gap
* @group generators
* @param {number} steps * @param {number} steps
* @example * @example
* gap(3) // "~@3" * gap(3) // "~@3"
@ -1238,6 +1282,7 @@ export const gap = (steps) => new Pattern(() => [], steps);
/** /**
* Does absolutely nothing.. * Does absolutely nothing..
* @name silence * @name silence
* @group generators
* @example * @example
* silence // "~" * silence // "~"
*/ */
@ -1249,6 +1294,7 @@ export const nothing = gap(0);
/** /**
* A discrete value that repeats once per cycle. * A discrete value that repeats once per cycle.
* *
* @group generators
* @returns {Pattern} * @returns {Pattern}
* @example * @example
* pure('e4') // "e4" * pure('e4') // "e4"
@ -1290,7 +1336,10 @@ export function reify(thing) {
return pure(thing); return pure(thing);
} }
/** Takes a list of patterns, and returns a pattern of lists. /**
* Takes a list of patterns, and returns a pattern of lists.
*
* @group transforms
*/ */
export function sequenceP(pats) { export function sequenceP(pats) {
let result = pure([]); let result = pure([]);
@ -1303,6 +1352,7 @@ export function sequenceP(pats) {
/** /**
* The given items are played at the same time at the same length. * The given items are played at the same time at the same length.
* *
* @group structure
* @return {Pattern} * @return {Pattern}
* @synonyms polyrhythm, pr * @synonyms polyrhythm, pr
* @example * @example
@ -1387,6 +1437,7 @@ export function stackBy(by, ...pats) {
/** /**
* Concatenation: combines a list of patterns, switching between them successively, one per cycle. * Concatenation: combines a list of patterns, switching between them successively, one per cycle.
* *
* @group combiners
* @return {Pattern} * @return {Pattern}
* @synonyms cat * @synonyms cat
* @example * @example
@ -1420,6 +1471,7 @@ export function slowcat(...pats) {
} }
/** Concatenation: combines a list of patterns, switching between them successively, one per cycle. Unlike slowcat, this version will skip cycles. /** Concatenation: combines a list of patterns, switching between them successively, one per cycle. Unlike slowcat, this version will skip cycles.
* @group combiners
* @param {...any} items - The items to concatenate * @param {...any} items - The items to concatenate
* @return {Pattern} * @return {Pattern}
*/ */
@ -1435,6 +1487,7 @@ export function slowcatPrime(...pats) {
/** The given items are con**cat**enated, where each one takes one cycle. /** The given items are con**cat**enated, where each one takes one cycle.
* *
* @group combiners
* @param {...any} items - The items to concatenate * @param {...any} items - The items to concatenate
* @synonyms slowcat * @synonyms slowcat
* @return {Pattern} * @return {Pattern}
@ -1456,6 +1509,7 @@ export function cat(...pats) {
* Allows to arrange multiple patterns together over multiple cycles. * Allows to arrange multiple patterns together over multiple cycles.
* Takes a variable number of arrays with two elements specifying the number of cycles and the pattern to use. * Takes a variable number of arrays with two elements specifying the number of cycles and the pattern to use.
* *
* @group combiners
* @return {Pattern} * @return {Pattern}
* @example * @example
* arrange( * arrange(
@ -1473,6 +1527,7 @@ export function arrange(...sections) {
* Similarly to `arrange`, allows you to arrange multiple patterns together over multiple cycles. * Similarly to `arrange`, allows you to arrange multiple patterns together over multiple cycles.
* Unlike `arrange`, you specify a start and stop time for each pattern rather than duration, which * Unlike `arrange`, you specify a start and stop time for each pattern rather than duration, which
* means that patterns can overlap. * means that patterns can overlap.
* @group combiners
* @return {Pattern} * @return {Pattern}
* @example * @example
seqPLoop([0, 2, "bd(3,8)"], seqPLoop([0, 2, "bd(3,8)"],
@ -1517,6 +1572,7 @@ export function sequence(...pats) {
} }
/** Like **cat**, but the items are crammed into one cycle. /** Like **cat**, but the items are crammed into one cycle.
* @group combiners
* @synonyms sequence, fastcat * @synonyms sequence, fastcat
* @example * @example
* seq("e5", "b4", ["d5", "c5"]).note() * seq("e5", "b4", ["d5", "c5"]).note()
@ -1690,6 +1746,7 @@ function stepRegister(name, func, patternify = true, preserveSteps = false, join
* Assumes a numerical pattern. Returns a new pattern with all values rounded * Assumes a numerical pattern. Returns a new pattern with all values rounded
* to the nearest integer. * to the nearest integer.
* @name round * @name round
* @group math
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
* @example * @example
@ -1698,13 +1755,13 @@ function stepRegister(name, func, patternify = true, preserveSteps = false, join
export const round = register('round', function (pat) { export const round = register('round', function (pat) {
return pat.asNumber().fmap((v) => Math.round(v)); return pat.asNumber().fmap((v) => Math.round(v));
}); });
/** /**
* Assumes a numerical pattern. Returns a new pattern with all values set to * Assumes a numerical pattern. Returns a new pattern with all values set to
* their mathematical floor. E.g. `3.7` replaced with to `3`, and `-4.2` * their mathematical floor. E.g. `3.7` replaced with to `3`, and `-4.2`
* replaced with `-5`. * replaced with `-5`.
* @name floor * @name floor
* @memberof Pattern * @memberof Pattern
* @group math
* @returns Pattern * @returns Pattern
* @example * @example
* note("42 42.1 42.5 43".floor()) * note("42 42.1 42.5 43".floor())
@ -1719,6 +1776,7 @@ export const floor = register('floor', function (pat) {
* replaced with `-4`. * replaced with `-4`.
* @name ceil * @name ceil
* @memberof Pattern * @memberof Pattern
* @group math
* @returns Pattern * @returns Pattern
* @example * @example
* note("42 42.1 42.5 43".ceil()) * note("42 42.1 42.5 43".ceil())
@ -1729,6 +1787,7 @@ export const ceil = register('ceil', function (pat) {
/** /**
* Assumes a numerical pattern, containing unipolar values in the range 0 .. * Assumes a numerical pattern, containing unipolar values in the range 0 ..
* 1. Returns a new pattern with values scaled to the bipolar range -1 .. 1 * 1. Returns a new pattern with values scaled to the bipolar range -1 .. 1
* @group math
* @returns Pattern * @returns Pattern
* @noAutocomplete * @noAutocomplete
*/ */
@ -1739,6 +1798,7 @@ export const toBipolar = register('toBipolar', function (pat) {
/** /**
* Assumes a numerical pattern, containing bipolar values in the range -1 .. 1 * Assumes a numerical pattern, containing bipolar values in the range -1 .. 1
* Returns a new pattern with values scaled to the unipolar range 0 .. 1 * Returns a new pattern with values scaled to the unipolar range 0 .. 1
* @group math
* @returns Pattern * @returns Pattern
* @noAutocomplete * @noAutocomplete
*/ */
@ -1752,6 +1812,7 @@ export const fromBipolar = register('fromBipolar', function (pat) {
* Most useful in combination with continuous patterns. * Most useful in combination with continuous patterns.
* @name range * @name range
* @memberof Pattern * @memberof Pattern
* @group math
* @returns Pattern * @returns Pattern
* @example * @example
* s("[bd sd]*2,hh*8") * s("[bd sd]*2,hh*8")
@ -1767,6 +1828,7 @@ export const range = register('range', function (min, max, pat) {
* following an exponential curve. * following an exponential curve.
* @name rangex * @name rangex
* @memberof Pattern * @memberof Pattern
* @group math
* @returns Pattern * @returns Pattern
* @example * @example
* s("[bd sd]*2,hh*8") * s("[bd sd]*2,hh*8")
@ -1781,6 +1843,7 @@ export const rangex = register('rangex', function (min, max, pat) {
* Returns a new pattern with values scaled to the given min/max range. * Returns a new pattern with values scaled to the given min/max range.
* @name range2 * @name range2
* @memberof Pattern * @memberof Pattern
* @group math
* @returns Pattern * @returns Pattern
* @example * @example
* s("[bd sd]*2,hh*8") * s("[bd sd]*2,hh*8")
@ -1795,6 +1858,7 @@ export const range2 = register('range2', function (min, max, pat) {
* Returns a new pattern with just numbers. * Returns a new pattern with just numbers.
* @name ratio * @name ratio
* @memberof Pattern * @memberof Pattern
* @group math
* @returns Pattern * @returns Pattern
* @example * @example
* ratio("1, 5:4, 3:2").mul(110) * ratio("1, 5:4, 3:2").mul(110)
@ -1813,6 +1877,7 @@ export const ratio = register('ratio', (pat) =>
// Structural and temporal transformations // Structural and temporal transformations
/** Compress each cycle into the given timespan, leaving a gap /** Compress each cycle into the given timespan, leaving a gap
* @group structure
* @example * @example
* cat( * cat(
* s("bd sd").compress(.25,.75), * s("bd sd").compress(.25,.75),
@ -1834,6 +1899,7 @@ export const { compressSpan, compressspan } = register(['compressSpan', 'compres
/** /**
* speeds up a pattern like fast, but rather than it playing multiple times as fast would it instead leaves a gap in the remaining space of the cycle. For example, the following will play the sound pattern "bd sn" only once but compressed into the first half of the cycle, i.e. twice as fast. * speeds up a pattern like fast, but rather than it playing multiple times as fast would it instead leaves a gap in the remaining space of the cycle. For example, the following will play the sound pattern "bd sn" only once but compressed into the first half of the cycle, i.e. twice as fast.
* @group structure
* @name fastGap * @name fastGap
* @synonyms fastgap * @synonyms fastgap
* @example * @example
@ -1871,6 +1937,7 @@ export const { fastGap, fastgap } = register(['fastGap', 'fastgap'], function (f
/** /**
* Similar to `compress`, but doesn't leave gaps, and the 'focus' can be bigger than a cycle * Similar to `compress`, but doesn't leave gaps, and the 'focus' can be bigger than a cycle
* @group structure
* @example * @example
* s("bd hh sd hh").focus(1/4, 3/4) * s("bd hh sd hh").focus(1/4, 3/4)
*/ */
@ -1888,6 +1955,7 @@ export const { focusSpan, focusspan } = register(['focusSpan', 'focusspan'], fun
}); });
/** The ply function repeats each event the given number of times. /** The ply function repeats each event the given number of times.
* @group structure
* @example * @example
* s("bd ~ sd cp").ply("<1 2 3>") * s("bd ~ sd cp").ply("<1 2 3>")
*/ */
@ -1902,6 +1970,7 @@ export const ply = register('ply', function (factor, pat) {
/** /**
* Speed up a pattern by the given factor. Used by "*" in mini notation. * Speed up a pattern by the given factor. Used by "*" in mini notation.
* *
* @group structure
* @name fast * @name fast
* @synonyms density * @synonyms density
* @memberof Pattern * @memberof Pattern
@ -1926,6 +1995,7 @@ export const { fast, density } = register(
/** /**
* Both speeds up the pattern (like 'fast') and the sample playback (like 'speed'). * Both speeds up the pattern (like 'fast') and the sample playback (like 'speed').
* @group structure
* @example * @example
* s("bd sd:2").hurry("<1 2 4 3>").slow(1.5) * s("bd sd:2").hurry("<1 2 4 3>").slow(1.5)
*/ */
@ -1936,6 +2006,7 @@ export const hurry = register('hurry', function (r, pat) {
/** /**
* Slow down a pattern over the given number of cycles. Like the "/" operator in mini notation. * Slow down a pattern over the given number of cycles. Like the "/" operator in mini notation.
* *
* @group structure
* @name slow * @name slow
* @synonyms sparsity * @synonyms sparsity
* @memberof Pattern * @memberof Pattern
@ -1953,6 +2024,7 @@ export const { slow, sparsity } = register(['slow', 'sparsity'], function (facto
/** /**
* Carries out an operation 'inside' a cycle. * Carries out an operation 'inside' a cycle.
* @group structure
* @example * @example
* "0 1 2 3 4 3 2 1".inside(4, rev).scale('C major').note() * "0 1 2 3 4 3 2 1".inside(4, rev).scale('C major').note()
* // "0 1 2 3 4 3 2 1".slow(4).rev().fast(4).scale('C major').note() * // "0 1 2 3 4 3 2 1".slow(4).rev().fast(4).scale('C major').note()
@ -1963,6 +2035,7 @@ export const inside = register('inside', function (factor, f, pat) {
/** /**
* Carries out an operation 'outside' a cycle. * Carries out an operation 'outside' a cycle.
* @group structure
* @example * @example
* "<[0 1] 2 [3 4] 5>".outside(4, rev).scale('C major').note() * "<[0 1] 2 [3 4] 5>".outside(4, rev).scale('C major').note()
* // "<[0 1] 2 [3 4] 5>".fast(4).rev().slow(4).scale('C major').note() * // "<[0 1] 2 [3 4] 5>".fast(4).rev().slow(4).scale('C major').note()
@ -1973,6 +2046,7 @@ export const outside = register('outside', function (factor, f, pat) {
/** /**
* Applies the given function every n cycles, starting from the last cycle. * Applies the given function every n cycles, starting from the last cycle.
* @group structure
* @name lastOf * @name lastOf
* @memberof Pattern * @memberof Pattern
* @param {number} n how many cycles * @param {number} n how many cycles
@ -1989,6 +2063,7 @@ export const lastOf = register('lastOf', function (n, func, pat) {
/** /**
* Applies the given function every n cycles, starting from the first cycle. * Applies the given function every n cycles, starting from the first cycle.
* @group structure
* @name firstOf * @name firstOf
* @memberof Pattern * @memberof Pattern
* @param {number} n how many cycles * @param {number} n how many cycles
@ -2000,6 +2075,7 @@ export const lastOf = register('lastOf', function (n, func, pat) {
/** /**
* An alias for `firstOf` * An alias for `firstOf`
* @group structure
* @name every * @name every
* @memberof Pattern * @memberof Pattern
* @param {number} n how many cycles * @param {number} n how many cycles
@ -2016,8 +2092,8 @@ export const { firstOf, every } = register(['firstOf', 'every'], function (n, fu
/** /**
* Like layer, but with a single function: * Like layer, but with a single function:
* @group structure
* @name apply * @name apply
* @memberof Pattern
* @example * @example
* "<c3 eb3 g3>".scale('C minor').apply(scaleTranspose("0,2,4")).note() * "<c3 eb3 g3>".scale('C minor').apply(scaleTranspose("0,2,4")).note()
*/ */
@ -2028,6 +2104,7 @@ export const apply = register('apply', function (func, pat) {
/** /**
* Plays the pattern at the given cycles per minute. * Plays the pattern at the given cycles per minute.
* @group structure
* @deprecated * @deprecated
* @example * @example
* s("<bd sd>,hh*2").cpm(90) // = 90 bpm * s("<bd sd>,hh*2").cpm(90) // = 90 bpm
@ -2040,6 +2117,7 @@ export const cpm = register('cpm', function (cpm, pat) {
/** /**
* Nudge a pattern to start earlier in time. Equivalent of Tidal's <~ operator * Nudge a pattern to start earlier in time. Equivalent of Tidal's <~ operator
* *
* @group structure
* @name early * @name early
* @memberof Pattern * @memberof Pattern
* @param {number | Pattern} cycles number of cycles to nudge left * @param {number | Pattern} cycles number of cycles to nudge left
@ -2060,6 +2138,7 @@ export const early = register(
/** /**
* Nudge a pattern to start later in time. Equivalent of Tidal's ~> operator * Nudge a pattern to start later in time. Equivalent of Tidal's ~> operator
* *
* @group structure
* @name late * @name late
* @memberof Pattern * @memberof Pattern
* @param {number | Pattern} cycles number of cycles to nudge right * @param {number | Pattern} cycles number of cycles to nudge right
@ -2080,6 +2159,7 @@ export const late = register(
/** /**
* Plays a portion of a pattern, specified by the beginning and end of a time span. The new resulting pattern is played over the time period of the original pattern: * Plays a portion of a pattern, specified by the beginning and end of a time span. The new resulting pattern is played over the time period of the original pattern:
* *
* @group structure
* @example * @example
* s("bd*2 hh*3 [sd bd]*2 perc").zoom(0.25, 0.75) * s("bd*2 hh*3 [sd bd]*2 perc").zoom(0.25, 0.75)
* // s("hh*3 [sd bd]*2") // equivalent * // s("hh*3 [sd bd]*2") // equivalent
@ -2106,6 +2186,7 @@ export const { zoomArc, zoomarc } = register(['zoomArc', 'zoomarc'], function (a
/** /**
* Splits a pattern into the given number of slices, and plays them according to a pattern of slice numbers. * Splits a pattern into the given number of slices, and plays them according to a pattern of slice numbers.
* Similar to `slice`, but slices up patterns rather than sound samples. * Similar to `slice`, but slices up patterns rather than sound samples.
* @group structure
* @param {number} number of slices * @param {number} number of slices
* @param {number} slices to play * @param {number} slices to play
* @example * @example
@ -2133,6 +2214,7 @@ export const bite = register(
/** /**
* Selects the given fraction of the pattern and repeats that part to fill the remainder of the cycle. * Selects the given fraction of the pattern and repeats that part to fill the remainder of the cycle.
* @group structure
* @param {number} fraction fraction to select * @param {number} fraction fraction to select
* @example * @example
* s("lt ht mt cp, [hh oh]*2").linger("<1 .5 .25 .125>") * s("lt ht mt cp, [hh oh]*2").linger("<1 .5 .25 .125>")
@ -2153,6 +2235,7 @@ export const linger = register(
/** /**
* Samples the pattern at a rate of n events per cycle. Useful for turning a continuous pattern into a discrete one. * Samples the pattern at a rate of n events per cycle. Useful for turning a continuous pattern into a discrete one.
* @group structure
* @name segment * @name segment
* @synonyms seg * @synonyms seg
* @param {number} segments number of segments per cycle * @param {number} segments number of segments per cycle
@ -2165,6 +2248,7 @@ export const { segment, seg } = register(['segment', 'seg'], function (rate, pat
/** /**
* The function `swingBy x n` breaks each cycle into `n` slices, and then delays events in the second half of each slice by the amount `x`, which is relative to the size of the (half) slice. So if `x` is 0 it does nothing, `0.5` delays for half the note duration, and 1 will wrap around to doing nothing again. The end result is a shuffle or swing-like rhythm * The function `swingBy x n` breaks each cycle into `n` slices, and then delays events in the second half of each slice by the amount `x`, which is relative to the size of the (half) slice. So if `x` is 0 it does nothing, `0.5` delays for half the note duration, and 1 will wrap around to doing nothing again. The end result is a shuffle or swing-like rhythm
* @group structure
* @param {number} subdivision * @param {number} subdivision
* @param {number} offset * @param {number} offset
* @example * @example
@ -2174,6 +2258,7 @@ export const swingBy = register('swingBy', (swing, n, pat) => pat.inside(n, late
/** /**
* Shorthand for swingBy with 1/3: * Shorthand for swingBy with 1/3:
* @group structure
* @param {number} subdivision * @param {number} subdivision
* @example * @example
* s("hh*8").swing(4) * s("hh*8").swing(4)
@ -2183,6 +2268,7 @@ export const swing = register('swing', (n, pat) => pat.swingBy(1 / 3, n));
/** /**
* Swaps 1s and 0s in a binary pattern. * Swaps 1s and 0s in a binary pattern.
* @group structure
* @name invert * @name invert
* @synonyms inv * @synonyms inv
* @example * @example
@ -2200,6 +2286,7 @@ export const { invert, inv } = register(
/** /**
* Applies the given function whenever the given pattern is in a true state. * Applies the given function whenever the given pattern is in a true state.
* @group structure
* @name when * @name when
* @memberof Pattern * @memberof Pattern
* @param {Pattern} binary_pat * @param {Pattern} binary_pat
@ -2214,6 +2301,7 @@ export const when = register('when', function (on, func, pat) {
/** /**
* Superimposes the function result on top of the original pattern, delayed by the given time. * Superimposes the function result on top of the original pattern, delayed by the given time.
* @group structure
* @name off * @name off
* @memberof Pattern * @memberof Pattern
* @param {Pattern | number} time offset time * @param {Pattern | number} time offset time
@ -2230,6 +2318,7 @@ export const off = register('off', function (time_pat, func, pat) {
* Returns a new pattern where every other cycle is played once, twice as * Returns a new pattern where every other cycle is played once, twice as
* fast, and offset in time by one quarter of a cycle. Creates a kind of * fast, and offset in time by one quarter of a cycle. Creates a kind of
* breakbeat feel. * breakbeat feel.
* @group structure
* @returns Pattern * @returns Pattern
*/ */
export const brak = register('brak', function (pat) { export const brak = register('brak', function (pat) {
@ -2239,6 +2328,7 @@ export const brak = register('brak', function (pat) {
/** /**
* Reverse all haps in a pattern * Reverse all haps in a pattern
* *
* @group structure
* @name rev * @name rev
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
@ -2272,6 +2362,7 @@ export const rev = register(
/** Like press, but allows you to specify the amount by which each /** Like press, but allows you to specify the amount by which each
* event is shifted. pressBy(0.5) is the same as press, while * event is shifted. pressBy(0.5) is the same as press, while
* pressBy(1/3) shifts each event by a third of its timespan. * pressBy(1/3) shifts each event by a third of its timespan.
* @group structure
* @example * @example
* stack(s("hh*4"), * stack(s("hh*4"),
* s("bd mt sd ht").pressBy("<0 0.5 0.25>") * s("bd mt sd ht").pressBy("<0 0.5 0.25>")
@ -2283,6 +2374,7 @@ export const pressBy = register('pressBy', function (r, pat) {
/** /**
* Syncopates a rhythm, by shifting each event halfway into its timespan. * Syncopates a rhythm, by shifting each event halfway into its timespan.
* @group structure
* @example * @example
* stack(s("hh*4"), * stack(s("hh*4"),
* s("bd mt sd ht").every(4, press) * s("bd mt sd ht").every(4, press)
@ -2294,6 +2386,7 @@ export const press = register('press', function (pat) {
/** /**
* Silences a pattern. * Silences a pattern.
* @group structure
* @example * @example
* stack( * stack(
* s("bd").hush(), * s("bd").hush(),
@ -2306,6 +2399,7 @@ Pattern.prototype.hush = function () {
/** /**
* Applies `rev` to a pattern every other cycle, so that the pattern alternates between forwards and backwards. * Applies `rev` to a pattern every other cycle, so that the pattern alternates between forwards and backwards.
* @group structure
* @example * @example
* note("c d e g").palindrome() * note("c d e g").palindrome()
*/ */
@ -2320,6 +2414,7 @@ export const palindrome = register(
/** /**
* Jux with adjustable stereo width. 0 = mono, 1 = full stereo. * Jux with adjustable stereo width. 0 = mono, 1 = full stereo.
* @group structure
* @name juxBy * @name juxBy
* @synonyms juxby * @synonyms juxby
* @example * @example
@ -2341,6 +2436,7 @@ export const { juxBy, juxby } = register(['juxBy', 'juxby'], function (by, func,
/** /**
* The jux function creates strange stereo effects, by applying a function to a pattern, but only in the right-hand channel. * The jux function creates strange stereo effects, by applying a function to a pattern, but only in the right-hand channel.
* @group structure
* @example * @example
* s("bd lt [~ ht] mt cp ~ bd hh").jux(rev) * s("bd lt [~ ht] mt cp ~ bd hh").jux(rev)
* @example * @example
@ -2354,6 +2450,7 @@ export const jux = register('jux', function (func, pat) {
/** /**
* Superimpose and offset multiple times, applying the given function each time. * Superimpose and offset multiple times, applying the given function each time.
* @group structure
* @name echoWith * @name echoWith
* @synonyms echowith, stutWith, stutwith * @synonyms echowith, stutWith, stutwith
* @param {number} times how many times to repeat * @param {number} times how many times to repeat
@ -2373,6 +2470,7 @@ export const { echoWith, echowith, stutWith, stutwith } = register(
/** /**
* Superimpose and offset multiple times, gradually decreasing the velocity * Superimpose and offset multiple times, gradually decreasing the velocity
* @group structure
* @name echo * @name echo
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
@ -2388,6 +2486,7 @@ export const echo = register('echo', function (times, time, feedback, pat) {
/** /**
* Deprecated. Like echo, but the last 2 parameters are flipped. * Deprecated. Like echo, but the last 2 parameters are flipped.
* @group structure
* @name stut * @name stut
* @param {number} times how many times to repeat * @param {number} times how many times to repeat
* @param {number} feedback velocity multiplicator for each iteration * @param {number} feedback velocity multiplicator for each iteration
@ -2409,6 +2508,7 @@ export const applyN = register('applyN', function (n, func, p) {
/** /**
* The plyWith function repeats each event the given number of times, applying the given function to each event.\n * The plyWith function repeats each event the given number of times, applying the given function to each event.\n
* @group structure
* @name plyWith * @name plyWith
* @synonyms plywith * @synonyms plywith
* @param {number} factor how many times to repeat * @param {number} factor how many times to repeat
@ -2431,6 +2531,7 @@ export const plyWith = register(['plyWith', 'plywith'], function (factor, func,
/** /**
* The plyForEach function repeats each event the given number of times, applying the given function to each event. * The plyForEach function repeats each event the given number of times, applying the given function to each event.
* This version of ply uses the iteration index as an argument to the function, similar to echoWith. * This version of ply uses the iteration index as an argument to the function, similar to echoWith.
* @group structure
* @name plyForEach * @name plyForEach
* @synonyms plyforeach * @synonyms plyforeach
* @param {number} factor how many times to repeat * @param {number} factor how many times to repeat
@ -2452,6 +2553,7 @@ export const plyForEach = register(['plyForEach', 'plyforeach'], function (facto
/** /**
* Divides a pattern into a given number of subdivisions, plays the subdivisions in order, but increments the starting subdivision each cycle. The pattern wraps to the first subdivision after the last subdivision is played. * Divides a pattern into a given number of subdivisions, plays the subdivisions in order, but increments the starting subdivision each cycle. The pattern wraps to the first subdivision after the last subdivision is played.
* @group structure
* @name iter * @name iter
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
@ -2479,6 +2581,7 @@ export const iter = register(
/** /**
* Like `iter`, but plays the subdivisions in reverse order. Known as iter' in tidalcycles * Like `iter`, but plays the subdivisions in reverse order. Known as iter' in tidalcycles
* @group structure
* @name iterBack * @name iterBack
* @synonyms iterback * @synonyms iterback
* @memberof Pattern * @memberof Pattern
@ -2497,6 +2600,7 @@ export const { iterBack, iterback } = register(
/** /**
* Repeats each cycle the given number of times. * Repeats each cycle the given number of times.
* @group structure
* @name repeatCycles * @name repeatCycles
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
@ -2520,6 +2624,7 @@ export const { repeatCycles } = register(
/** /**
* Divides a pattern into a given number of parts, then cycles through those parts in turn, applying the given function to each part in turn (one part per cycle). * Divides a pattern into a given number of parts, then cycles through those parts in turn, applying the given function to each part in turn (one part per cycle).
* @group structure
* @name chunk * @name chunk
* @synonyms slowChunk, slowchunk * @synonyms slowChunk, slowchunk
* @memberof Pattern * @memberof Pattern
@ -2551,6 +2656,7 @@ export const { chunk, slowchunk, slowChunk } = register(
/** /**
* Like `chunk`, but cycles through the parts in reverse order. Known as chunk' in tidalcycles * Like `chunk`, but cycles through the parts in reverse order. Known as chunk' in tidalcycles
* @group structure
* @name chunkBack * @name chunkBack
* @synonyms chunkback * @synonyms chunkback
* @memberof Pattern * @memberof Pattern
@ -2571,6 +2677,7 @@ export const { chunkBack, chunkback } = register(
/** /**
* Like `chunk`, but the cycles of the source pattern aren't repeated * Like `chunk`, but the cycles of the source pattern aren't repeated
* for each set of chunks. * for each set of chunks.
* @group structure
* @name fastChunk * @name fastChunk
* @synonyms fastchunk * @synonyms fastchunk
* @memberof Pattern * @memberof Pattern
@ -2591,6 +2698,7 @@ export const { fastchunk, fastChunk } = register(
/** /**
* Like `chunk`, but the function is applied to a looped subcycle of the source pattern. * Like `chunk`, but the function is applied to a looped subcycle of the source pattern.
* @group structure
* @name chunkInto * @name chunkInto
* @synonyms chunkinto * @synonyms chunkinto
* @memberof Pattern * @memberof Pattern
@ -2604,6 +2712,7 @@ export const { chunkinto, chunkInto } = register(['chunkinto', 'chunkInto'], fun
/** /**
* Like `chunkInto`, but moves backwards through the chunks. * Like `chunkInto`, but moves backwards through the chunks.
* @group structure
* @name chunkBackInto * @name chunkBackInto
* @synonyms chunkbackinto * @synonyms chunkbackinto
* @memberof Pattern * @memberof Pattern
@ -2634,6 +2743,7 @@ export const bypass = register(
/** /**
* Loops the pattern inside an `offset` for `cycles`. * Loops the pattern inside an `offset` for `cycles`.
* If you think of the entire span of time in cycles as a ribbon, you can cut a single piece and loop it. * If you think of the entire span of time in cycles as a ribbon, you can cut a single piece and loop it.
* @group structure
* @name ribbon * @name ribbon
* @synonyms rib * @synonyms rib
* @param {number} offset start point of loop in cycles * @param {number} offset start point of loop in cycles
@ -2662,6 +2772,7 @@ export const hsl = register('hsl', (h, s, l, pat) => {
/** /**
* Tags each Hap with an identifier. Good for filtering. The function populates Hap.context.tags (Array). * Tags each Hap with an identifier. Good for filtering. The function populates Hap.context.tags (Array).
* @name tag * @name tag
* @group structure
* @noAutocomplete * @noAutocomplete
* @param {string} tag anything unique * @param {string} tag anything unique
*/ */
@ -2672,6 +2783,7 @@ Pattern.prototype.tag = function (tag) {
/** /**
* Filters haps using the given function * Filters haps using the given function
* @name filter * @name filter
* @group structure
* @param {Function} test function to test Hap * @param {Function} test function to test Hap
* @example * @example
* s("hh!7 oh").filter(hap => hap.value.s==='hh') * s("hh!7 oh").filter(hap => hap.value.s==='hh')
@ -2681,6 +2793,7 @@ export const filter = register('filter', (test, pat) => pat.withHaps((haps) => h
/** /**
* Filters haps by their begin time * Filters haps by their begin time
* @name filterWhen * @name filterWhen
* @group structure
* @noAutocomplete * @noAutocomplete
* @param {Function} test function to test Hap.whole.begin * @param {Function} test function to test Hap.whole.begin
*/ */
@ -2689,6 +2802,7 @@ export const filterWhen = register('filterWhen', (test, pat) => pat.filter((h) =
/** /**
* Use within to apply a function to only a part of a pattern. * Use within to apply a function to only a part of a pattern.
* @name within * @name within
* @group structure
* @param {number} start start within cycle (0 - 1) * @param {number} start start within cycle (0 - 1)
* @param {number} end end within cycle (0 - 1). Must be > start * @param {number} end end within cycle (0 - 1). Must be > start
* @param {Function} func function to be applied to the sub-pattern * @param {Function} func function to be applied to the sub-pattern
@ -2763,6 +2877,7 @@ export function _match(span, hap_p) {
* *Experimental* * *Experimental*
* *
* Speeds a pattern up or down, to fit to the given number of steps per cycle. * Speeds a pattern up or down, to fit to the given number of steps per cycle.
* @group structure
* @example * @example
* sound("bd sd cp").pace(4) * sound("bd sd cp").pace(4)
* // The same as sound("{bd sd cp}%4") or sound("<bd sd cp>*4") * // The same as sound("{bd sd cp}%4") or sound("<bd sd cp>*4")
@ -2804,6 +2919,7 @@ export function _polymeterListSteps(steps, ...args) {
* *Experimental* * *Experimental*
* *
* Aligns the steps of the patterns, creating polymeters. The patterns are repeated until they all fit the cycle. For example, in the below the first pattern is repeated twice, and the second is repeated three times, to fit the lowest common multiple of six steps. * Aligns the steps of the patterns, creating polymeters. The patterns are repeated until they all fit the cycle. For example, in the below the first pattern is repeated twice, and the second is repeated three times, to fit the lowest common multiple of six steps.
* @group structure
* @synonyms pm * @synonyms pm
* @example * @example
* // The same as note("{c eb g, c2 g2}%6") * // The same as note("{c eb g, c2 g2}%6")
@ -2836,6 +2952,7 @@ export function polymeter(...args) {
* The steps can either be inferred from the pattern, or provided as a [length, pattern] pair. * The steps can either be inferred from the pattern, or provided as a [length, pattern] pair.
* Has the alias `timecat`. * Has the alias `timecat`.
* @name stepcat * @name stepcat
* @group combiners
* @synonyms timeCat, timecat * @synonyms timeCat, timecat
* @return {Pattern} * @return {Pattern}
* @example * @example
@ -2893,6 +3010,7 @@ export function stepcat(...timepats) {
* Concatenates patterns stepwise, according to an inferred 'steps per cycle'. * Concatenates patterns stepwise, according to an inferred 'steps per cycle'.
* Similar to `stepcat`, but if an argument is a list, the whole pattern will alternate between the elements in the list. * Similar to `stepcat`, but if an argument is a list, the whole pattern will alternate between the elements in the list.
* *
* @group combiners
* @return {Pattern} * @return {Pattern}
* @example * @example
* stepalt(["bd cp", "mt"], "bd").sound() * stepalt(["bd cp", "mt"], "bd").sound()
@ -2919,6 +3037,7 @@ export function stepalt(...groups) {
* *
* Takes the given number of steps from a pattern (dropping the rest). * Takes the given number of steps from a pattern (dropping the rest).
* A positive number will take steps from the start of a pattern, and a negative number from the end. * A positive number will take steps from the start of a pattern, and a negative number from the end.
* @group structure
* @return {Pattern} * @return {Pattern}
* @example * @example
* "bd cp ht mt".take("2").sound() * "bd cp ht mt".take("2").sound()
@ -2963,6 +3082,7 @@ export const take = stepRegister('take', function (i, pat) {
* *
* Drops the given number of steps from a pattern. * Drops the given number of steps from a pattern.
* A positive number will drop steps from the start of a pattern, and a negative number from the end. * A positive number will drop steps from the start of a pattern, and a negative number from the end.
* @group structure
* @return {Pattern} * @return {Pattern}
* @example * @example
* "tha dhi thom nam".drop("1").sound().bank("mridangam") * "tha dhi thom nam".drop("1").sound().bank("mridangam")
@ -2991,6 +3111,7 @@ export const drop = stepRegister('drop', function (i, pat) {
* `extend` is similar to `fast` in that it increases its density, but it also increases the step count * `extend` is similar to `fast` in that it increases its density, but it also increases the step count
* accordingly. So `stepcat("a b".extend(2), "c d")` would be the same as `"a b a b c d"`, whereas * accordingly. So `stepcat("a b".extend(2), "c d")` would be the same as `"a b a b c d"`, whereas
* `stepcat("a b".fast(2), "c d")` would be the same as `"[a b] [a b] c d"`. * `stepcat("a b".fast(2), "c d")` would be the same as `"[a b] [a b] c d"`.
* @group structure
* @example * @example
* stepcat( * stepcat(
* sound("bd bd - cp").extend(2), * sound("bd bd - cp").extend(2),
@ -3005,6 +3126,7 @@ export const extend = stepRegister('extend', function (factor, pat) {
* *Experimental* * *Experimental*
* *
* Expands the step size of the pattern by the given factor. * Expands the step size of the pattern by the given factor.
* @group structure
* @example * @example
* sound("tha dhi thom nam").bank("mridangam").expand("3 2 1 1 2 3").pace(8) * sound("tha dhi thom nam").bank("mridangam").expand("3 2 1 1 2 3").pace(8)
*/ */
@ -3016,6 +3138,7 @@ export const expand = stepRegister('expand', function (factor, pat) {
* *Experimental* * *Experimental*
* *
* Contracts the step size of the pattern by the given factor. See also `expand`. * Contracts the step size of the pattern by the given factor. See also `expand`.
* @group structure
* @example * @example
* sound("tha dhi thom nam").bank("mridangam").contract("3 2 1 1 2 3").pace(8) * sound("tha dhi thom nam").bank("mridangam").contract("3 2 1 1 2 3").pace(8)
*/ */
@ -3070,6 +3193,7 @@ export const shrinklist = (amount, pat) => pat.shrinklist(amount);
* Progressively shrinks the pattern by 'n' steps until there's nothing left, or if a second value is given (using mininotation list syntax with `:`), * Progressively shrinks the pattern by 'n' steps until there's nothing left, or if a second value is given (using mininotation list syntax with `:`),
* that number of times. * that number of times.
* A positive number will progressively drop steps from the start of a pattern, and a negative number from the end. * A positive number will progressively drop steps from the start of a pattern, and a negative number from the end.
* @group structure
* @return {Pattern} * @return {Pattern}
* @example * @example
* "tha dhi thom nam".shrink("1").sound() * "tha dhi thom nam".shrink("1").sound()
@ -3109,6 +3233,7 @@ export const shrink = register(
* Progressively grows the pattern by 'n' steps until the full pattern is played, or if a second value is given (using mininotation list syntax with `:`), * Progressively grows the pattern by 'n' steps until the full pattern is played, or if a second value is given (using mininotation list syntax with `:`),
* that number of times. * that number of times.
* A positive number will progressively grow steps from the start of a pattern, and a negative number from the end. * A positive number will progressively grow steps from the start of a pattern, and a negative number from the end.
* @group structure
* @return {Pattern} * @return {Pattern}
* @example * @example
* "tha dhi thom nam".grow("1").sound() * "tha dhi thom nam".grow("1").sound()
@ -3148,7 +3273,8 @@ export const grow = register(
* Inserts a pattern into a list of patterns. On the first repetition it will be inserted at the end of the list, then moved backwards through the list * Inserts a pattern into a list of patterns. On the first repetition it will be inserted at the end of the list, then moved backwards through the list
* on successive repetitions. The patterns are added together stepwise, with all repetitions taking place over a single cycle. Using `pace` to set the * on successive repetitions. The patterns are added together stepwise, with all repetitions taking place over a single cycle. Using `pace` to set the
* number of steps per cycle is therefore usually recommended. * number of steps per cycle is therefore usually recommended.
* *
* @group combiners
* @return {Pattern} * @return {Pattern}
* @example * @example
* "[c g]".tour("e f", "e f g", "g f e c").note() * "[c g]".tour("e f", "e f g", "g f e c").note()
@ -3175,6 +3301,7 @@ Pattern.prototype.tour = function (...many) {
* 'zips' together the steps of the provided patterns. This can create a long repetition, taking place over a single, dense cycle. * 'zips' together the steps of the provided patterns. This can create a long repetition, taking place over a single, dense cycle.
* Using `pace` to set the number of steps per cycle is therefore usually recommended. * Using `pace` to set the number of steps per cycle is therefore usually recommended.
* *
* @group combiners
* @returns {Pattern} * @returns {Pattern}
* @example * @example
* zip("e f", "e f g", "g [f e] a f4 c").note() * zip("e f", "e f g", "g [f e] a f4 c").note()
@ -3226,6 +3353,7 @@ Pattern.prototype.steps = Pattern.prototype.pace;
* Cuts each sample into the given number of parts, allowing you to explore a technique known as 'granular synthesis'. * 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. * It turns a pattern of samples into a pattern of parts of samples.
* @name chop * @name chop
* @group transforms
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
* @example * @example
@ -3256,6 +3384,7 @@ export const chop = register('chop', function (n, pat) {
/** /**
* Cuts each sample into the given number of parts, triggering progressive portions of each sample at each loop. * Cuts each sample into the given number of parts, triggering progressive portions of each sample at each loop.
* @name striate * @name striate
* @group transforms
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
* @example * @example
@ -3274,6 +3403,7 @@ export const striate = register('striate', function (n, pat) {
/** /**
* Makes the sample fit the given number of cycles by changing the speed. * Makes the sample fit the given number of cycles by changing the speed.
* @name loopAt * @name loopAt
* @group transforms
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
* @example * @example
@ -3292,6 +3422,7 @@ const _loopAt = function (factor, pat, cps = 0.5) {
* Chops samples into the given number of slices, triggering those slices with a given pattern of slice numbers. * Chops samples into the given number of slices, triggering those slices with a given pattern of slice numbers.
* Instead of a number, it also accepts a list of numbers from 0 to 1 to slice at specific points. * Instead of a number, it also accepts a list of numbers from 0 to 1 to slice at specific points.
* @name slice * @name slice
* @group transforms
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
* @example * @example
@ -3327,6 +3458,7 @@ export const slice = register(
* make something happen on event time * make something happen on event time
* uses browser timeout which is innacurate for audio tasks * uses browser timeout which is innacurate for audio tasks
* @name onTriggerTime * @name onTriggerTime
* @group external_io
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
* @example * @example
@ -3344,6 +3476,7 @@ Pattern.prototype.onTriggerTime = function (func) {
/** /**
* Works the same as slice, but changes the playback speed of each slice to match the duration of its step. * Works the same as slice, but changes the playback speed of each slice to match the duration of its step.
* @name splice * @name splice
* @group transforms
* @example * @example
* samples('github:tidalcycles/dirt-samples') * samples('github:tidalcycles/dirt-samples')
* s("breaks165") * s("breaks165")
@ -3381,6 +3514,7 @@ export const { loopAt, loopat } = register(['loopAt', 'loopat'], function (facto
* Makes the sample fit its event duration. Good for rhythmical loops like drum breaks. * Makes the sample fit its event duration. Good for rhythmical loops like drum breaks.
* Similar to `loopAt`. * Similar to `loopAt`.
* @name fit * @name fit
* @group transforms
* @example * @example
* samples({ rhodes: 'https://cdn.freesound.org/previews/132/132051_316502-lq.mp3' }) * samples({ rhodes: 'https://cdn.freesound.org/previews/132/132051_316502-lq.mp3' })
* s("rhodes/2").fit() * s("rhodes/2").fit()
@ -3406,6 +3540,7 @@ export const fit = register('fit', (pat) =>
* given by a global clock and this function will be * given by a global clock and this function will be
* deprecated/removed. * deprecated/removed.
* @name loopAtCps * @name loopAtCps
* @group transforms
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
* @example * @example
@ -3432,6 +3567,7 @@ let fadeGain = (p) => (p < 0.5 ? 1 : 1 - (p - 0.5) / 0.5);
* - 1 = (no left, full right) * - 1 = (no left, full right)
* *
* @name xfade * @name xfade
* @group combiners
* @example * @example
* xfade(s("bd*2"), "<0 .25 .5 .75 1>", s("hh*8")) * xfade(s("bd*2"), "<0 .25 .5 .75 1>", s("hh*8"))
*/ */
@ -3453,6 +3589,7 @@ Pattern.prototype.xfade = function (pos, b) {
* creates a structure pattern from divisions of a cycle * creates a structure pattern from divisions of a cycle
* especially useful for creating rhythms * especially useful for creating rhythms
* @name beat * @name beat
* @group structure
* @example * @example
* s("bd").beat("0,7,10", 16) * s("bd").beat("0,7,10", 16)
* @example * @example
@ -3529,6 +3666,7 @@ export const _morph = (from, to, by) => {
* sine.slow(8) // slowly morph between the rhythms * sine.slow(8) // slowly morph between the rhythms
* ) * )
* ) * )
* @group structure
*/ */
export const morph = (frompat, topat, bypat) => { export const morph = (frompat, topat, bypat) => {
frompat = reify(frompat); frompat = reify(frompat);

52
packages/core/signal.mjs
View file

@ -24,6 +24,7 @@ export const signal = (func) => {
* A sawtooth signal between 0 and 1. * A sawtooth signal between 0 and 1.
* *
* @return {Pattern} * @return {Pattern}
* @group generators
* @example * @example
* note("<c3 [eb3,g3] g2 [g3,bb3]>*8") * note("<c3 [eb3,g3] g2 [g3,bb3]>*8")
* .clip(saw.slow(2)) * .clip(saw.slow(2))
@ -38,6 +39,7 @@ export const saw = signal((t) => t % 1);
* A sawtooth signal between -1 and 1 (like `saw`, but bipolar). * A sawtooth signal between -1 and 1 (like `saw`, but bipolar).
* *
* @return {Pattern} * @return {Pattern}
* @group generators
*/ */
export const saw2 = saw.toBipolar(); export const saw2 = saw.toBipolar();
@ -45,6 +47,7 @@ export const saw2 = saw.toBipolar();
* A sawtooth signal between 1 and 0 (like `saw`, but flipped). * A sawtooth signal between 1 and 0 (like `saw`, but flipped).
* *
* @return {Pattern} * @return {Pattern}
* @group generators
* @example * @example
* note("<c3 [eb3,g3] g2 [g3,bb3]>*8") * note("<c3 [eb3,g3] g2 [g3,bb3]>*8")
* .clip(isaw.slow(2)) * .clip(isaw.slow(2))
@ -59,6 +62,7 @@ export const isaw = signal((t) => 1 - (t % 1));
* A sawtooth signal between 1 and -1 (like `saw2`, but flipped). * A sawtooth signal between 1 and -1 (like `saw2`, but flipped).
* *
* @return {Pattern} * @return {Pattern}
* @group generators
*/ */
export const isaw2 = isaw.toBipolar(); export const isaw2 = isaw.toBipolar();
@ -66,12 +70,14 @@ export const isaw2 = isaw.toBipolar();
* A sine signal between -1 and 1 (like `sine`, but bipolar). * A sine signal between -1 and 1 (like `sine`, but bipolar).
* *
* @return {Pattern} * @return {Pattern}
* @group generators
*/ */
export const sine2 = signal((t) => Math.sin(Math.PI * 2 * t)); export const sine2 = signal((t) => Math.sin(Math.PI * 2 * t));
/** /**
* A sine signal between 0 and 1. * A sine signal between 0 and 1.
* @return {Pattern} * @return {Pattern}
* @group generators
* @example * @example
* n(sine.segment(16).range(0,15)) * n(sine.segment(16).range(0,15))
* .scale("C:minor") * .scale("C:minor")
@ -83,6 +89,7 @@ export const sine = sine2.fromBipolar();
* A cosine signal between 0 and 1. * A cosine signal between 0 and 1.
* *
* @return {Pattern} * @return {Pattern}
* @group generators
* @example * @example
* n(stack(sine,cosine).segment(16).range(0,15)) * n(stack(sine,cosine).segment(16).range(0,15))
* .scale("C:minor") * .scale("C:minor")
@ -94,12 +101,14 @@ export const cosine = sine._early(Fraction(1).div(4));
* A cosine signal between -1 and 1 (like `cosine`, but bipolar). * A cosine signal between -1 and 1 (like `cosine`, but bipolar).
* *
* @return {Pattern} * @return {Pattern}
* @group generators
*/ */
export const cosine2 = sine2._early(Fraction(1).div(4)); export const cosine2 = sine2._early(Fraction(1).div(4));
/** /**
* A square signal between 0 and 1. * A square signal between 0 and 1.
* @return {Pattern} * @return {Pattern}
* @group generators
* @example * @example
* n(square.segment(4).range(0,7)).scale("C:minor") * n(square.segment(4).range(0,7)).scale("C:minor")
* *
@ -110,6 +119,7 @@ export const square = signal((t) => Math.floor((t * 2) % 2));
* A square signal between -1 and 1 (like `square`, but bipolar). * A square signal between -1 and 1 (like `square`, but bipolar).
* *
* @return {Pattern} * @return {Pattern}
* @group generators
*/ */
export const square2 = square.toBipolar(); export const square2 = square.toBipolar();
@ -117,6 +127,7 @@ export const square2 = square.toBipolar();
* A triangle signal between 0 and 1. * A triangle signal between 0 and 1.
* *
* @return {Pattern} * @return {Pattern}
* @group generators
* @example * @example
* n(tri.segment(8).range(0,7)).scale("C:minor") * n(tri.segment(8).range(0,7)).scale("C:minor")
* *
@ -127,6 +138,7 @@ export const tri = fastcat(saw, isaw);
* A triangle signal between -1 and 1 (like `tri`, but bipolar). * A triangle signal between -1 and 1 (like `tri`, but bipolar).
* *
* @return {Pattern} * @return {Pattern}
* @group generators
*/ */
export const tri2 = fastcat(saw2, isaw2); export const tri2 = fastcat(saw2, isaw2);
@ -134,6 +146,7 @@ export const tri2 = fastcat(saw2, isaw2);
* An inverted triangle signal between 1 and 0 (like `tri`, but flipped). * An inverted triangle signal between 1 and 0 (like `tri`, but flipped).
* *
* @return {Pattern} * @return {Pattern}
* @group generators
* @example * @example
* n(itri.segment(8).range(0,7)).scale("C:minor") * n(itri.segment(8).range(0,7)).scale("C:minor")
* *
@ -144,6 +157,7 @@ export const itri = fastcat(isaw, saw);
* An inverted triangle signal between -1 and 1 (like `itri`, but bipolar). * An inverted triangle signal between -1 and 1 (like `itri`, but bipolar).
* *
* @return {Pattern} * @return {Pattern}
* @group generators
*/ */
export const itri2 = fastcat(isaw2, saw2); export const itri2 = fastcat(isaw2, saw2);
@ -151,6 +165,7 @@ export const itri2 = fastcat(isaw2, saw2);
* A signal representing the cycle time. * A signal representing the cycle time.
* *
* @return {Pattern} * @return {Pattern}
* @group generators
*/ */
export const time = signal(id); export const time = signal(id);
@ -158,6 +173,7 @@ export const time = signal(id);
* The mouse's x position value ranges from 0 to 1. * The mouse's x position value ranges from 0 to 1.
* @name mousex * @name mousex
* @return {Pattern} * @return {Pattern}
* @group external_io
* @example * @example
* n(mousex.segment(4).range(0,7)).scale("C:minor") * n(mousex.segment(4).range(0,7)).scale("C:minor")
* *
@ -167,6 +183,7 @@ export const time = signal(id);
* The mouse's y position value ranges from 0 to 1. * The mouse's y position value ranges from 0 to 1.
* @name mousey * @name mousey
* @return {Pattern} * @return {Pattern}
* @group external_io
* @example * @example
* n(mousey.segment(4).range(0,7)).scale("C:minor") * n(mousey.segment(4).range(0,7)).scale("C:minor")
* *
@ -221,6 +238,7 @@ const timeToRands = (t, n) => timeToRandsPrime(timeToIntSeed(t), n);
/** /**
* A discrete pattern of numbers from 0 to n-1 * A discrete pattern of numbers from 0 to n-1
* @group generators
* @example * @example
* n(run(4)).scale("C4:pentatonic") * n(run(4)).scale("C4:pentatonic")
* // n("0 1 2 3").scale("C4:pentatonic") * // n("0 1 2 3").scale("C4:pentatonic")
@ -231,6 +249,7 @@ export const run = (n) => saw.range(0, n).round().segment(n);
* Creates a pattern from a binary number. * Creates a pattern from a binary number.
* *
* @name binary * @name binary
* @group generators
* @param {number} n - input number to convert to binary * @param {number} n - input number to convert to binary
* @example * @example
* "hh".s().struct(binary(5)) * "hh".s().struct(binary(5))
@ -245,6 +264,7 @@ export const binary = (n) => {
* Creates a pattern from a binary number, padded to n bits long. * Creates a pattern from a binary number, padded to n bits long.
* *
* @name binaryN * @name binaryN
* @group generators
* @param {number} n - input number to convert to binary * @param {number} n - input number to convert to binary
* @param {number} nBits - pattern length, defaults to 16 * @param {number} nBits - pattern length, defaults to 16
* @example * @example
@ -280,6 +300,7 @@ const _rearrangeWith = (ipat, n, pat) => {
* Slices a pattern into the given number of parts, then plays those parts in random order. * Slices a pattern into the given number of parts, then plays those parts in random order.
* Each part will be played exactly once per cycle. * Each part will be played exactly once per cycle.
* @name shuffle * @name shuffle
* @group transforms
* @example * @example
* note("c d e f").sound("piano").shuffle(4) * note("c d e f").sound("piano").shuffle(4)
* @example * @example
@ -293,6 +314,7 @@ export const shuffle = register('shuffle', (n, pat) => {
* Slices a pattern into the given number of parts, then plays those parts at random. Similar to `shuffle`, * Slices a pattern into the given number of parts, then plays those parts at random. Similar to `shuffle`,
* but parts might be played more than once, or not at all, per cycle. * but parts might be played more than once, or not at all, per cycle.
* @name scramble * @name scramble
* @group transforms
* @example * @example
* note("c d e f").sound("piano").scramble(4) * note("c d e f").sound("piano").scramble(4)
* @example * @example
@ -306,6 +328,7 @@ export const scramble = register('scramble', (n, pat) => {
* A continuous pattern of random numbers, between 0 and 1. * A continuous pattern of random numbers, between 0 and 1.
* *
* @name rand * @name rand
* @group generators
* @example * @example
* // randomly change the cutoff * // randomly change the cutoff
* s("bd*4,hh*8").cutoff(rand.range(500,8000)) * s("bd*4,hh*8").cutoff(rand.range(500,8000))
@ -323,6 +346,7 @@ export const _brandBy = (p) => rand.fmap((x) => x < p);
* A continuous pattern of 0 or 1 (binary random), with a probability for the value being 1 * A continuous pattern of 0 or 1 (binary random), with a probability for the value being 1
* *
* @name brandBy * @name brandBy
* @group generators
* @param {number} probability - a number between 0 and 1 * @param {number} probability - a number between 0 and 1
* @example * @example
* s("hh*10").pan(brandBy(0.2)) * s("hh*10").pan(brandBy(0.2))
@ -333,6 +357,7 @@ export const brandBy = (pPat) => reify(pPat).fmap(_brandBy).innerJoin();
* A continuous pattern of 0 or 1 (binary random) * A continuous pattern of 0 or 1 (binary random)
* *
* @name brand * @name brand
* @group generators
* @example * @example
* s("hh*10").pan(brand) * s("hh*10").pan(brand)
*/ */
@ -344,6 +369,7 @@ export const _irand = (i) => rand.fmap((x) => Math.trunc(x * i));
* A continuous pattern of random integers, between 0 and n-1. * A continuous pattern of random integers, between 0 and n-1.
* *
* @name irand * @name irand
* @group generators
* @param {number} n max value (exclusive) * @param {number} n max value (exclusive)
* @example * @example
* // randomly select scale notes from 0 - 7 (= C to C) * // randomly select scale notes from 0 - 7 (= C to C)
@ -366,6 +392,7 @@ export const __chooseWith = (pat, xs) => {
/** /**
* Choose from the list of values (or patterns of values) using the given * Choose from the list of values (or patterns of values) using the given
* pattern of numbers, which should be in the range of 0..1 * pattern of numbers, which should be in the range of 0..1
* @group transforms
* @param {Pattern} pat * @param {Pattern} pat
* @param {*} xs * @param {*} xs
* @returns {Pattern} * @returns {Pattern}
@ -379,6 +406,7 @@ export const chooseWith = (pat, xs) => {
/** /**
* As with {chooseWith}, but the structure comes from the chosen values, rather * As with {chooseWith}, but the structure comes from the chosen values, rather
* than the pattern you're using to choose with. * than the pattern you're using to choose with.
* @group transforms
* @param {Pattern} pat * @param {Pattern} pat
* @param {*} xs * @param {*} xs
* @returns {Pattern} * @returns {Pattern}
@ -389,6 +417,7 @@ export const chooseInWith = (pat, xs) => {
/** /**
* Chooses randomly from the given list of elements. * Chooses randomly from the given list of elements.
* @group transforms
* @param {...any} xs values / patterns to choose from. * @param {...any} xs values / patterns to choose from.
* @returns {Pattern} - a continuous pattern. * @returns {Pattern} - a continuous pattern.
* @example * @example
@ -404,6 +433,7 @@ export const chooseOut = choose;
* Chooses from the given list of values (or patterns of values), according * Chooses from the given list of values (or patterns of values), according
* to the pattern that the method is called on. The pattern should be in * to the pattern that the method is called on. The pattern should be in
* the range 0 .. 1. * the range 0 .. 1.
* @group transforms
* @param {...any} xs * @param {...any} xs
* @returns {Pattern} * @returns {Pattern}
*/ */
@ -414,6 +444,7 @@ Pattern.prototype.choose = function (...xs) {
/** /**
* As with choose, but the pattern that this method is called on should be * As with choose, but the pattern that this method is called on should be
* in the range -1 .. 1 * in the range -1 .. 1
* @group transforms
* @param {...any} xs * @param {...any} xs
* @returns {Pattern} * @returns {Pattern}
*/ */
@ -423,6 +454,7 @@ Pattern.prototype.choose2 = function (...xs) {
/** /**
* Picks one of the elements at random each cycle. * Picks one of the elements at random each cycle.
* @group transforms
* @synonyms randcat * @synonyms randcat
* @returns {Pattern} * @returns {Pattern}
* @example * @example
@ -465,6 +497,7 @@ const wchooseWith = (...args) => _wchooseWith(...args).outerJoin();
/** /**
* Chooses randomly from the given list of elements by giving a probability to each element * Chooses randomly from the given list of elements by giving a probability to each element
* @group transforms
* @param {...any} pairs arrays of value and weight * @param {...any} pairs arrays of value and weight
* @returns {Pattern} - a continuous pattern. * @returns {Pattern} - a continuous pattern.
* @example * @example
@ -474,6 +507,7 @@ export const wchoose = (...pairs) => wchooseWith(rand, ...pairs);
/** /**
* Picks one of the elements at random each cycle by giving a probability to each element * Picks one of the elements at random each cycle by giving a probability to each element
* @group transforms
* @synonyms wrandcat * @synonyms wrandcat
* @returns {Pattern} * @returns {Pattern}
* @example * @example
@ -521,6 +555,7 @@ export const berlinWith = (tpat) => {
/** /**
* Generates a continuous pattern of [perlin noise](https://en.wikipedia.org/wiki/Perlin_noise), in the range 0..1. * Generates a continuous pattern of [perlin noise](https://en.wikipedia.org/wiki/Perlin_noise), in the range 0..1.
* *
* @group generators
* @name perlin * @name perlin
* @example * @example
* // randomly change the cutoff * // randomly change the cutoff
@ -533,6 +568,7 @@ export const perlin = perlinWith(time.fmap((v) => Number(v)));
* Generates a continuous pattern of [berlin noise](conceived by Jame Coyne and Jade Rowland as a joke but turned out to be surprisingly cool and useful, * Generates a continuous pattern of [berlin noise](conceived by Jame Coyne and Jade Rowland as a joke but turned out to be surprisingly cool and useful,
* like perlin noise but with sawtooth waves), in the range 0..1. * like perlin noise but with sawtooth waves), in the range 0..1.
* *
* @group generators
* @name berlin * @name berlin
* @example * @example
* // ascending arpeggios * // ascending arpeggios
@ -553,6 +589,7 @@ export const degradeByWith = register(
* 0 = 0% chance of removal * 0 = 0% chance of removal
* 1 = 100% chance of removal * 1 = 100% chance of removal
* *
* @group transforms
* @name degradeBy * @name degradeBy
* @memberof Pattern * @memberof Pattern
* @param {number} amount - a number between 0 and 1 * @param {number} amount - a number between 0 and 1
@ -578,6 +615,7 @@ export const degradeBy = register(
* *
* Randomly removes 50% of events from the pattern. Shorthand for `.degradeBy(0.5)` * Randomly removes 50% of events from the pattern. Shorthand for `.degradeBy(0.5)`
* *
* @group transforms
* @name degrade * @name degrade
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
@ -594,6 +632,7 @@ export const degrade = register('degrade', (pat) => pat._degradeBy(0.5), true, t
* 1 = 0% chance of removal * 1 = 0% chance of removal
* Events that would be removed by degradeBy are let through by undegradeBy and vice versa (see second example). * Events that would be removed by degradeBy are let through by undegradeBy and vice versa (see second example).
* *
* @group transforms
* @name undegradeBy * @name undegradeBy
* @memberof Pattern * @memberof Pattern
* @param {number} amount - a number between 0 and 1 * @param {number} amount - a number between 0 and 1
@ -622,6 +661,7 @@ export const undegradeBy = register(
* Inverse of `degrade`: Randomly removes 50% of events from the pattern. Shorthand for `.undegradeBy(0.5)` * Inverse of `degrade`: Randomly removes 50% of events from the pattern. Shorthand for `.undegradeBy(0.5)`
* Events that would be removed by degrade are let through by undegrade and vice versa (see second example). * Events that would be removed by degrade are let through by undegrade and vice versa (see second example).
* *
* @group transforms
* @name undegrade * @name undegrade
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
@ -640,6 +680,7 @@ export const undegrade = register('undegrade', (pat) => pat._undegradeBy(0.5), t
* Randomly applies the given function by the given probability. * Randomly applies the given function by the given probability.
* Similar to `someCyclesBy` * Similar to `someCyclesBy`
* *
* @group transforms
* @name sometimesBy * @name sometimesBy
* @memberof Pattern * @memberof Pattern
* @param {number | Pattern} probability - a number between 0 and 1 * @param {number | Pattern} probability - a number between 0 and 1
@ -659,6 +700,7 @@ export const sometimesBy = register('sometimesBy', function (patx, func, pat) {
* *
* Applies the given function with a 50% chance * Applies the given function with a 50% chance
* *
* @group transforms
* @name sometimes * @name sometimes
* @memberof Pattern * @memberof Pattern
* @param {function} function - the transformation to apply * @param {function} function - the transformation to apply
@ -680,6 +722,7 @@ export const sometimes = register('sometimes', function (func, pat) {
* @param {number | Pattern} probability - a number between 0 and 1 * @param {number | Pattern} probability - a number between 0 and 1
* @param {function} function - the transformation to apply * @param {function} function - the transformation to apply
* @returns Pattern * @returns Pattern
* @group transforms
* @example * @example
* s("bd,hh*8").someCyclesBy(.3, x=>x.speed("0.5")) * s("bd,hh*8").someCyclesBy(.3, x=>x.speed("0.5"))
*/ */
@ -702,6 +745,7 @@ export const someCyclesBy = register('someCyclesBy', function (patx, func, pat)
* @name someCycles * @name someCycles
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
* @group transforms
* @example * @example
* s("bd,hh*8").someCycles(x=>x.speed("0.5")) * s("bd,hh*8").someCycles(x=>x.speed("0.5"))
*/ */
@ -716,6 +760,7 @@ export const someCycles = register('someCycles', function (func, pat) {
* @name often * @name often
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
* @group transforms
* @example * @example
* s("hh*8").often(x=>x.speed("0.5")) * s("hh*8").often(x=>x.speed("0.5"))
*/ */
@ -730,6 +775,7 @@ export const often = register('often', function (func, pat) {
* @name rarely * @name rarely
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
* @group transforms
* @example * @example
* s("hh*8").rarely(x=>x.speed("0.5")) * s("hh*8").rarely(x=>x.speed("0.5"))
*/ */
@ -741,6 +787,7 @@ export const rarely = register('rarely', function (func, pat) {
* *
* Shorthand for `.sometimesBy(0.1, fn)` * Shorthand for `.sometimesBy(0.1, fn)`
* *
* @group transforms
* @name almostNever * @name almostNever
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
@ -755,6 +802,7 @@ export const almostNever = register('almostNever', function (func, pat) {
* *
* Shorthand for `.sometimesBy(0.9, fn)` * Shorthand for `.sometimesBy(0.9, fn)`
* *
* @group transforms
* @name almostAlways * @name almostAlways
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
@ -769,6 +817,7 @@ export const almostAlways = register('almostAlways', function (func, pat) {
* *
* Shorthand for `.sometimesBy(0, fn)` (never calls fn) * Shorthand for `.sometimesBy(0, fn)` (never calls fn)
* *
* @group transforms
* @name never * @name never
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
@ -783,6 +832,7 @@ export const never = register('never', function (_, pat) {
* *
* Shorthand for `.sometimesBy(1, fn)` (always calls fn) * Shorthand for `.sometimesBy(1, fn)` (always calls fn)
* *
* @group transforms
* @name always * @name always
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
@ -811,6 +861,7 @@ export function _keyDown(keyname) {
* Do something on a keypress, or array of keypresses * Do something on a keypress, or array of keypresses
* [Key name reference](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values) * [Key name reference](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values)
* *
* @group external_io
* @name whenKey * @name whenKey
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern
@ -827,6 +878,7 @@ export const whenKey = register('whenKey', function (input, func, pat) {
* returns true when a key or array of keys is held * returns true when a key or array of keys is held
* [Key name reference](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values) * [Key name reference](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values)
* *
* @group external_io
* @name keyDown * @name keyDown
* @memberof Pattern * @memberof Pattern
* @returns Pattern * @returns Pattern

6
website/src/repl/components/panel/Reference.jsx
View file

@ -39,9 +39,11 @@ const GROUP_DISPLAY_NAMES = {
external_io: 'External I/O', external_io: 'External I/O',
effects: 'Effects', effects: 'Effects',
ungrouped: 'Ungrouped', ungrouped: 'Ungrouped',
structure: 'Structure',
transforms: 'Transforms',
}; };
const GROUP_ORDER = ['effects', 'external_io', 'ungrouped']; const GROUP_ORDER = ['effects', 'transforms', 'structure', 'ungrouped', 'external_io'];
export function Reference() { export function Reference() {
const [search, setSearch] = useState(''); const [search, setSearch] = useState('');
@ -93,7 +95,7 @@ export function Reference() {
{sortedGroups.map(([groupId, groupEntries]) => ( {sortedGroups.map(([groupId, groupEntries]) => (
<> <>
<h4 key={`group-${groupId}`} className="font-semibold text-foreground"> <h4 key={`group-${groupId}`} className="font-semibold text-foreground">
{GROUP_DISPLAY_NAMES[groupId] || groupId} {GROUP_DISPLAY_NAMES[groupId] || groupId} ({groupEntries.length})
</h4> </h4>
{groupEntries.map((entry, i) => ( {groupEntries.map((entry, i) => (
<a <a