Conditions
This page will present you all the functions that can be used to add conditions to your patterns. Each function will be presented following the same model:
- Type signature: how the function is declared on the Haskell side.
- Description: verbal description of the function.
- Examples: a small list of examples that you can copy/paste in your editor.
Every and the others#
every#
every is function that allows you to apply another function conditionally. It takes three inputs: how often the function should be applied (e.g. 3 to apply it every 3 cycles), the function to be applied, and the pattern you are applying it to. For example: to reverse a pattern every three cycles (and for the other two play it normally)
Note that if the function you're applying itself requires additional parameters (such as fast 2 to make a pattern twice as fast), then you'll need to wrap it in parenthesis, like so:
Otherwise, the every function will think it is being passed too many parameters.
every'#
every' is a generalisation of every, taking one additional argument. The additional argument allows you to offset the function you are applying.
For example, every' 3 0 (fast 2) will speed up the cycle on cycles 0,3,6,… whereas every' 3 1 (fast 2) will transform the pattern on cycles 1,4,7,…
With this in mind, setting the second argument of every' to 0 gives the equivalent every function. For example, every 3 is equivalent to every' 3 0.
foldEvery#
foldEvery is similar to chaining multiple every functions together. It transforms a pattern with a function, once per any of the given number of cycles. If a particular cycle is the start of more than one of the given cycle periods, then it it applied more than once.
when#
Only when the given test function returns True the given pattern transformation is applied. The test function will be called with the current cycle as a number.
The above will only apply striate 4 to the pattern if the current cycle number contains the number 4. So the fourth cycle will be striated and the fourteenth and so on. Expect lots of striates after cycle number 399.
whenT#
This function is not documented.
whenmod#
whenmod has a similar form and behavior to every, but requires an additional number. It applies the function to the pattern, when the remainder of the current loop number divided by the first parameter, is greater or equal than the second parameter. For example the following makes every other block of four loops twice as fast:
The "sometimes" family#
sometimes#
sometimes is function, that applies another function to a pattern, around 50% of the time, at random. It takes two inputs, the function to be applied, and the pattern you are applying it to.
For example to distort half the events in a pattern:
sometimes has a number of variants, which apply the function with different likelihood:
| function | Â likelihood |
|---|---|
| always | 100% |
| almostAlways | 90% |
| often | 75% |
| sometimes | 50% |
| rarely | 25% |
| almostNever | 10% |
| never | 0% |
sometimesBy#
If you want to be specific, you can use sometimesBy and a number, for example:
to apply the speed control on average 93 times out of a hundred.
someCycles#
someCycles is similar to sometimes, but instead of applying the given function to random events, it applies it to random cycles. For example the following will either distort all of the events in a cycle, or none of them:
someCyclesBy#
As with sometimesBy, if you want to be specific, you can use someCyclesBy and a number. For example:
will apply the speed control on average 93 cycles out of a hundred.
Choosing#
choose#
The choose function emits a stream of randomly choosen values from the given list, as a continuous pattern:
As with all continuous patterns, you have to be careful to give them structure; in this case choose gives you an infinitely detailed stream of random choices.
chooseby#
The chooseBy function is like choose but instead of selecting elements of the list randomly, it uses the given pattern to select elements.
will result in the pattern "a b c" .
wchoose#
wchoose is similar to choose, but allows you to 'weight' the choices, so some are more likely to be chosen than others. The following is similar to the previous example, but the 2 is twice as likely to be chosen than the 0 or 3.
caution
Prior to version 1.0.0 of Tidal, the weights had to add up to 1, but this is no longer the case.
wchooseby#
The wchooseBy function is like wchoose but instead of selecting elements of the list randomly, it uses the given pattern to select elements.
cycleChoose#
Similar to choose, but only picks once per cycle:
Boolean conditions#
struct#
struct places a rhythmic 'boolean' structure on the pattern you give it. For example:
... is the same as ...
The structure comes from a boolean pattern, i.e. a binary one containing true or false values. Above we only used true values, denoted by t. It's also possible to include false values with f, which struct will simply treat as silience. For example, this would have the same outcome as the above:
These true/false binary patterns become useful when you conditionally manipulate them, for example 'inverting' the values using every and inv:
In the above, the boolean values will be 'inverted' every third cycle, so that the structure comes from the fs rather than t. Note that euclidean patterns also create true/false values, for example:
In the above, the euclidean pattern creates "t f t f t f f t" which gets inverted to "f t f t f t t f" every third cycle. Note that if you prefer you can use 1 and 0 instead of t and f.
mask#
mask takes a boolean (aka binary) pattern and 'masks' another pattern with it. That is, events are only carried over if they match within a 'true' event in the binary pattern. For example consider this kind of messy rhythm without any rests:
If we apply a mask to it:
Due to the use of cat here, the same mask is first applied to "sn*8" and in the next cycle to "[cp4 bd4, hc*5]".
You could achieve the same effect by adding rests within the cat patterns, but mask allows you to do this more easily. It kind of keeps the rhythmic structure and you can change the used samples independently:
sew#
sew uses a pattern of boolean (true or false) values to switch between two other patterns. For example the following will play the first pattern for the first half of a cycle, and the second pattern for the other half.
The above combines two patterns of strings, and passes the result to the sound function. It's also possible to sew together two control patterns, for example:
You can also use Euclidean rhythm syntax in the boolean sequence:
stitch#
stitch uses the first (binary) pattern to switch between the following two patterns. The resulting structure comes from the binary pattern, not the source patterns. This differs from sew where the resulting structure comes from the source patterns. For example, the following uses a euclidean pattern to control CC0:
select#
Chooses between a list of patterns, using a pattern of floats (from 0 to 1).
selectF#
Chooses between a list of functions, using a pattern of floats (from 0 to 1)
pickF#
Chooses between a list of functions, using a pattern of integers.
squeeze#
Chooses between a list of patterns, using a pattern of integers.
euclid#
euclid creates a Euclidean rhythmic structure. It produces the same output as the Euclidean pattern string. For example:
is the same as:
euclid accepts two parameters that can be patterns:
euclidInv#
Inverts the pattern given by euclid. For example:
to hear that the hi-hat event fires on every one of the eight even beats that the bass drum does not.
euclidFull#
euclidFull is a convenience function for playing one pattern on the euclidean rhythm and a different pattern on the off-beat.
is equivalent to our above example.
contrast#
contrast is like a if-else-statement over patterns. For contrast t f p you can think of t al the true-branch, f as the false branch, and p as the test.
For contrast, you can use any control pattern as a test of equality: n "<0 1>", speed "0.5", or things like that. This lets you choose specific properties of the pattern you're transforming for testing, like in the following example:
where every note that isn't middle-c will be shifted down an octave but middle-c will be shifted up to c5.
Since the test given to contrast is also a pattern, you can do things like have it alternate between options:
If you listen to this you'll hear that which instrument is shifted up and which instrument is shifted down alternates between cycles.
contrastBy#
contrastBy is currently undocumented.
ifp#
ifp decides whether to apply one or another function depending on the result of a test function, which is passed the current cycle as a number. For example:
This will apply striate 4 for every even cycle, and # coarse "24 48" for every odd one.
tip
The test function does not rely on anything Tidal-specific, it uses plain Haskell functionality for operating on numbers. That is, it calculates the modulo of 2 of the current cycle which is either 0 (for even cycles) or 1. It then compares this value against 0 and returns the result, which is either True or False. This is what the first part of ifp's type signature signifies (Int -> Bool), a function that takes a whole number and returns either True or False.