From 9c8e39d83d4415cbdaab6960986fa2fe1ec2d569 Mon Sep 17 00:00:00 2001 From: Aria Date: Wed, 27 Aug 2025 16:27:36 -0500 Subject: [PATCH] Add.. a lot of doc strings --- packages/core/controls.mjs | 269 +++++++++++++++++++++++++++++ packages/superdough/superdough.mjs | 2 +- 2 files changed, 270 insertions(+), 1 deletion(-) diff --git a/packages/core/controls.mjs b/packages/core/controls.mjs index ddbfe98eb..a078c2b6f 100644 --- a/packages/core/controls.mjs +++ b/packages/core/controls.mjs @@ -1428,24 +1428,293 @@ export const { panorient } = registerControl('panorient'); // ['pitch2'], // ['pitch3'], // ['portamento'], +/** + * Selects which LFO number to use for modulation. Multiple LFOs + * can be applied using the ':' mininotation. There are an arbitrary number + * of LFOs available -- the number is only used to share LFOs across targets + * if desired (and to conserve processing power) + * + * @name lfoNum + * @param {number | Pattern} lfoNum Index of the LFO. + * setup: note("F2").sound("supersaw") + * .lpf(100) + * .lfoDepth(1000) + * .lfoRate(0.25) + * .lfoSynced(1) + * .lfoTarget("lpf") + * .lfoParam("frequency") + * .lfoNum(2) + * + * reuse: note("F3").sound("square").lpf(50) + * .lfoTarget("lpf") + * .lfoParam("frequency") + * .lfoNum(2) // uses the same LFO + */ export const { lfoNum } = registerControl('lfoNum'); + +/** + * Sets the target destination for the LFO modulation. Names are typically related + * to existing controls ("source", "lpf", "vibrato", etc.). You can try a value + * and if it fails, the console will print the available options. + * + * @name lfoTarget + * @param {string | Pattern} lfoTarget Target identifier for modulation. + * note("F2").sound("supersaw") + * .lpf(100) + * .lfoDepth(3000) + * .lfoRate(0.25) + * .lfoSynced(1) + * .lfoTarget("lpf") + * .lfoParam("frequency") + */ export const { lfoTarget } = registerControl('lfoTarget'); + +/** + * Chooses which parameter the LFO will modulate on the target. Parameter values + * are things like "frequency", "Q", "detune", etc. You can try a value + * and if it fails, the console will print the available options. + * + * @name lfoParam + * @param {string | Pattern} lfoParam Parameter name + * note("F2").sound("supersaw") + * .lpf(100) + * .lfoDepth(3000) + * .lfoRate(0.25) + * .lfoSynced(1) + * .lfoTarget("lpf") + * .lfoParam("frequency") + */ export const { lfoParam } = registerControl('lfoParam'); + +/** + * Controls the speed of the LFO. + * + * @name lfoRate + * @param {number | Pattern} lfoRate Frequency or tempo-relative value. + * note("F2").sound("supersaw") + * .lpf(100) + * .lfoTarget("lpf") + * .lfoParam("frequency") + * .lfoDepth(3000) + * .lfoRate(0.25) + */ export const { lfoRate } = registerControl('lfoRate'); + +/** + * Sets the modulation depth of the LFO. + * + * @name lfoDepth + * @param {number | Pattern} lfoDepth Modulation depth amount. + * note("F2").sound("supersaw") + * .lpf(100) + * .lfoTarget("lpf") + * .lfoParam("frequency") + * .lfoSynced(1) + * .lfoDepth(5000) + */ export const { lfoDepth } = registerControl('lfoDepth'); + +/** + * Applies a DC offset to the LFO signal. Normally the LFO varies from + * 0 to 1 (i.e. unipolar). By using an offset of -0.5, one can achieve + * a bipolar LFO. + * + * @name lfoDCOffset + * @param {number | Pattern} lfoDCOffset Offset amount. + * note("F2").sound("supersaw") + * .lpf(2000) + * .lfoTarget("lpf") + * .lfoParam("frequency") + * .lfoDepth(1000) + * .lfoRate(4) + * .lfoSynced(1) + * .lfoDCOffset(-0.5) + */ export const { lfoDCOffset } = registerControl('lfoDCOffset'); + +/** + * Selects the waveform shape of the LFO. Current options are + * triangle, square, sine, saw, ramp (corresponding to 0 through 4, + * respectively). + * + * @name lfoShape + * @param {number | Pattern} lfoShape Waveform type identifier. + * note("F2").sound("supersaw") + * .lpf(100) + * .lfoTarget("lpf") + * .lfoParam("frequency") + * .lfoDepth(1000) + * .lfoRate(4) + * .lfoSynced(1) + * .lfoShape(3) + */ export const { lfoShape } = registerControl('lfoShape'); + +/** + * Skews the LFO waveform. + * + * @name lfoSkew + * @param {number | Pattern} lfoSkew Skew amount (between 0 and 1). + * note("F2").sound("supersaw") + * .lpf(100) + * .lfoTarget("lpf") + * .lfoParam("frequency") + * .lfoDepth(1000) + * .lfoRate(4) + * .lfoSynced(1) + * .lfoSkew(0.75) + */ export const { lfoSkew } = registerControl('lfoSkew'); + +/** + * Adjusts the (exponential) curvature of the LFO waveform. + * + * @name lfoCurve + * @param {number | Pattern} lfoCurve Curve shaping amount. + * note("F2").sound("supersaw") + * .lpf(100) + * .lfoTarget("lpf") + * .lfoParam("frequency") + * .lfoDepth(1000) + * .lfoShape(3).lfoRate(4) + * .lfoSynced(1) + * .lfoCurve(0.95) + */ export const { lfoCurve } = registerControl('lfoCurve'); + +/** + * Determines whether the LFO is tempo-synced. + * + * @name lfoSynced + * @param {number | Pattern} lfoSynced Boolean flag (0 or 1). + * note("F2").sound("supersaw") + * .lpf(100) + * .lfoTarget("lpf") + * .lfoParam("frequency") + * .lfoDepth(1000) + * .lfoShape(3).lfoRate(2) + * .lfoSynced(1) + */ export const { lfoSynced } = registerControl('lfoSynced'); +/** + * Sets the target destination for the envelope modulation. Names are typically related + * to existing controls ("source", "lpf", "vibrato", etc.). You can try a value + * and if it fails, the console will print the available options. + * + * @name envTarget + * @param {number | Pattern} envTarget Target identifier for modulation. + * n(irand(12).seg(8)).scale("F#3:minor").room(1) + * .lpf(100) + * .envDepth("4800:400") + * .envTarget("source:lpf") + * .envParam("detune:frequency") + */ export const { envTarget } = registerControl('envTarget'); + +/** + * Chooses which parameter the LFO will modulate on the target. Parameter values + * are things like "frequency", "Q", "detune", etc. You can try a value + * and if it fails, the console will print the available options. + * + * @name envParam + * @param {number | Pattern} envParam Parameter index or identifier. + * n(irand(12).seg(8)).scale("F#3:minor").room(1) + * .lpf(100) + * .envDepth("4800:400") + * .envTarget("source:lpf") + * .envParam("detune:frequency") + */ export const { envParam } = registerControl('envParam'); + +/** + * Controls the attack time of the envelope. + * + * @name envAttack + * @param {number | Pattern} envAttack Duration of attack phase. + * n(irand(12).seg(8)).scale("F#3:minor").room(1) + * .lpf(500) + * .envDepth("4800:400") + * .envTarget("source:lpf") + * .envParam("detune:frequency") + * .envAttack(0.5) + */ export const { envAttack } = registerControl('envAttack'); + +/** + * Controls the decay time of the envelope. + * + * @name envDecay + * @param {number | Pattern} envDecay Duration of decay phase. + * n(irand(12).seg(8)).scale("F#3:minor").room(1) + * .lpf(100) + * .envDepth("4800:400") + * .envTarget("source:lpf") + * .envParam("detune:frequency") + * .envDecay("0.03:0.15").envCurve("exp:exp") + */ export const { envDecay } = registerControl('envDecay'); + +/** + * Sets the sustain level of the envelope. + * + * @name envSustain + * @param {number | Pattern} envSustain Sustain amplitude level. + * n(irand(12).seg(8)).scale("F#3:minor").room(1) + * .lpf(100) + * .envDepth("4800:400") + * .envTarget("source:lpf") + * .envParam("detune:frequency") + * .envDecay("0.03:0.15").envCurve("exp:exp") + * .envSustain(0.2) + */ export const { envSustain } = registerControl('envSustain'); + +/** + * Controls the release time of the envelope. + * + * @name envRelease + * @param {number | Pattern} envRelease Duration of release phase. + * @example + * n(irand(12).seg(8)).scale("F#3:minor").room(1) + * .lpf(100).release(3) + * .envDepth("4800:400") + * .envTarget("source:lpf") + * .envParam("detune:frequency") + * .envDecay("0.03:0.15").envCurve("exp:exp") + * .envSustain(0.5) + * .envRelease(3) + */ export const { envRelease } = registerControl('envRelease'); + +/** + * Selects the style of envelope: `exp` or `lin` (exponential or linear). + * + * @name envCurve + * @param {string | Pattern} envCurve Envelope curve style. + * @example + * n(irand(12).seg(8)).scale("F#3:minor").room(1) + * .lpf(100).release(2) + * .envTarget("source:lpf") + * .envParam("detune:frequency") + * .envDepth("500:4000") + * .envDecay("0.3:0.15") + * .envCurve("lin:exp") + */ export const { envCurve } = registerControl('envCurve'); + +/** + * Sets the modulation depth of the envelope. + * + * @name envDepth + * @param {number | Pattern} envDepth Modulation depth amount. + * @example + * n(irand(12).seg(8)).scale("F#3:minor").room(1) + * .lpf(100) + * .envTarget("source:lpf") + * .envParam("detune:frequency") + * .envDepth("4800:400") + */ export const { envDepth } = registerControl('envDepth'); // TODO: slide param for certain synths diff --git a/packages/superdough/superdough.mjs b/packages/superdough/superdough.mjs index 97f3900d0..91a97c17e 100644 --- a/packages/superdough/superdough.mjs +++ b/packages/superdough/superdough.mjs @@ -548,7 +548,7 @@ function _getNodeParams(node) { * @param {Object} params - Dictionary of modulation parameters. * @returns {Object[]} - Array of parameter objects, one per parameter modulation */ -function _splitParams(params, countKeys) { +function _splitParams(params) { const num = ['num', 'target', 'parameter'] // names used to indicate individual parameter modulations .map((k) => [params[k] ?? 0].flat().length) .reduce((a, v) => Math.max(a, v), 1);