From b695e090cd5f0f07795b9f41ad0f4a8d6943bc29 Mon Sep 17 00:00:00 2001 From: Felix Roos Date: Mon, 9 Jan 2023 23:27:30 +0100 Subject: [PATCH] docs: control params --- website/src/config.ts | 2 +- .../src/pages/functions/value-modifiers.mdx | 137 +++++++++++++++--- website/src/pages/learn/factories.mdx | 5 + website/src/pages/learn/signals.mdx | 26 ++-- 4 files changed, 134 insertions(+), 36 deletions(-) diff --git a/website/src/config.ts b/website/src/config.ts index 3d5c6069..c6cc9f59 100644 --- a/website/src/config.ts +++ b/website/src/config.ts @@ -59,7 +59,7 @@ export const SIDEBAR: Sidebar = { { text: 'Introduction', link: 'functions/intro' }, { text: 'Pattern Constructors', link: 'learn/factories' }, { text: 'Time Modifiers', link: 'learn/time-modifiers' }, - { text: 'Value Modifiers', link: 'functions/value-modifiers' }, + { text: 'Control Parameters', link: 'functions/value-modifiers' }, { text: 'Signals', link: 'learn/signals' }, { text: 'Conditional Modifiers', link: 'learn/conditional-modifiers' }, { text: 'Tonal Modifiers', link: 'learn/tonal' }, diff --git a/website/src/pages/functions/value-modifiers.mdx b/website/src/pages/functions/value-modifiers.mdx index 1f949b01..308dfd77 100644 --- a/website/src/pages/functions/value-modifiers.mdx +++ b/website/src/pages/functions/value-modifiers.mdx @@ -1,61 +1,154 @@ --- -title: Value Modifiers +title: Control Parameters layout: ../../layouts/MainLayout.astro --- import { MiniRepl } from '../../docs/MiniRepl'; import { JsDoc } from '../../docs/JsDoc'; -# Value Modifiers +# Control Parameters -## Notes +Besides functions that control time, we saw earlier that functions like `note` and `cutoff` control different parameters (short params) of an event. +Let's now look more closely at how these `param(eter) functions` work. -Notes are automatically available as variables: +# Parameter Functions - +A very powerful feature of tidal patterns is that each parameter can be controlled independently: -An important difference to the mini notation: -For sharp notes, the letter "s" is used instead of "#", because JavaScript does not support "#" in a variable name. +") +.gain(.8) +.s('sawtooth') +.log()`} +/> -The above is the same as: +In this example, the parameters `note`, `cutoff`, `gain` and `s` are controlled independently by either patterns or plain values (numbers / text). +After pressing play, we can observe the time and parameter values of each event (hap) in the output created by `.log()`. - +## Plain vs Parameterized Values -Using strings, you can also use "#". +Patterns that are not wrapped inside a param function will contain unlabeled `plain values`: -## Alternative Syntax +".log()`} /> -In the above example, we are nesting a function inside a function, which makes reading the parens a little more difficult. -To avoid getting to many nested parens, there is an alternative syntax to add a type to a pattern: +This will not generate any sound output, because Strudel could only guess which param is meant by these letters. - +Now compare that to the version wrapped in `note`: + +").log()`} /> + +Now it is clear that these letters are meant to be played as notes. +Under the hood, the `note` function (as well as all other param functions) +will wrap each plain value in an object. If the note function did not exist, we would need to write: + + + +This will have the same output, though it is rather unwieldy to read and write. + +## Wrapping Parameter Functions + +To avoid too much nesting, param functions can also be chained like this: + + + +This is equivalent to `note(cat('c','e','g')).log()`. You can use this with any function that declares a type (like `n`, `s`, `note`, `freq` etc), just make sure to leave the parens empty! -## Pattern.add +## Plain Value Modification + +Patterns of plain values can be modified with any of the following operators: + +").log()`} /> + +Here, the add function modifies the numbers on the left. +Again, there is no output because these numbers have no meaning without a param. + +## Param Value Modification + +To modify a parameter value, you can either: + +- Use the operator on the plain value pattern, inside the param function: + + ")).room(.1).log()`} /> + +- Similarly, use the operator on the plain value pattern and wrap it later: + + ").note().room(.1).log()`} /> + +- Specify which param should be modified inside the operator function: + + ")).log()`} /> + +- Modify _all_ numeral params: + + ").log()`} /> + +Which of these 3 ways to use strongly depends on the context! +Note that the order of chaining param functions also matters! +In the last example, the `room` value would not have changed if it was applied later: + +").room(.1).log()`} /> + +This shows how the execution of the chained functions goes from left to right. +In this case, the `.add` will only modify what's on the left side. + +# Operators + +This group of functions allows to modify the value of events. + +## add -## Pattern.sub +## sub -## Pattern.mul +## mul -## Pattern.div +## div -## Pattern.round +## round -## Pattern.apply +## floor - + -## Pattern.range +## ceil + + + +## range + +# Custom Parameters + +You can also create your own parameters: + + + +Multiple params can also be created in a more consice way, using `createParams`: + + + +Note that these params will not do anything until you give them meaning in your custom output! diff --git a/website/src/pages/learn/factories.mdx b/website/src/pages/learn/factories.mdx index 7bce19df..d98629d2 100644 --- a/website/src/pages/learn/factories.mdx +++ b/website/src/pages/learn/factories.mdx @@ -20,6 +20,7 @@ These are the equivalents used by the Mini Notation: | `timeCat([3,x],[2,y])` | `"x@2 y@2"` | | `polymeter([a, b, c], [x, y])` | `"{a b c, x y}"` | | `polymeterSteps(2, x, y, z)` | `"{x y z}%2"` | +| `silence` | `"~"` | ## cat @@ -56,3 +57,7 @@ As a chained function: ## polymeterSteps + +## silence + + diff --git a/website/src/pages/learn/signals.mdx b/website/src/pages/learn/signals.mdx index ee5614d1..0cf0f58e 100644 --- a/website/src/pages/learn/signals.mdx +++ b/website/src/pages/learn/signals.mdx @@ -56,54 +56,54 @@ These methods add random behavior to your Patterns. -## Pattern.degradeBy +## degradeBy -## Pattern.degrade +## degrade -## Pattern.undegradeBy +## undegradeBy -## Pattern.sometimesBy +## sometimesBy -## Pattern.sometimes +## sometimes -## Pattern.someCyclesBy +## someCyclesBy -## Pattern.someCycles +## someCycles -## Pattern.often +## often -## Pattern.rarely +## rarely -## Pattern.almostNever +## almostNever -## Pattern.almostAlways +## almostAlways -## Pattern.never +## never -## Pattern.always +## always