# 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.

## Conditions on cycle numbers

### every

`Type: every :: Pattern Int -> (Pattern a -> Pattern a) -> Pattern a -> Pattern a`

`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)

`d1 $ every 3 rev $ n "0 1 [~ 2] 3" # sound "arpy"`

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:

`d1 $ every 3 (fast 2) $ n "0 1 [~ 2] 3" # sound "arpy"`

Otherwise, the `every`

function will think it is being passed too many parameters.

### every'

`Type: every' :: Int -> Int -> (Pattern a -> Pattern a) -> Pattern a -> Pattern a`

`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`

.

The `every`

functions can be used to silence a full cycle or part of a cycle by using `silent`

or `mask "~"`

. Mask provides additional flexibility to turn on/off individual steps.

`d1 $ every 3 silent $ n "2 9 11 2" # s "hh27"`

d1 $ every 3 (mask "~") $ n "2 9 10 2" # s "hh27"

d1 $ every 3 (mask "0 0 0 0") $ n "2 9 11 2" # s "hh27"

### foldEvery

`Type: foldEvery :: [Int] -> (Pattern a -> Pattern a) -> Pattern a -> Pattern a`

`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.

`d1 $ foldEvery [5,3] (|+ n 1) $ s "moog" # legato 1`

The first `moog`

samples are tuned to C2, C3 and C4. Note how on cycles multiple of 3 or 5 the pitch is an octave higher, and on multiples of 15 the pitch is two octaves higher, as the transformation is applied twice.

### when

`Type: when :: (Int -> Bool) -> (Pattern a -> Pattern a) -> Pattern a -> Pattern a`

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.

`d1 $ when ((elem '4').show) (striate 4) $ sound "hh hc"`

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

`Type: whenT :: (Time -> Bool) -> (Pattern a -> Pattern a) -> Pattern a -> Pattern a`

Only when the given test function returns `True`

the given pattern transformation is applied. It differs from `when`

, being passed a continuous `Time`

value instead of the cycle number. Basically, a `Rational`

version of `when`

.

`d1 $ whenT ((< 0.5).(flip Data.Fixed.mod' 2)) (# speed 2) $ sound "hh(4,8) hc(3,8)"`

The above will apply `# speed 2`

only when the remainder of the current `Time`

divided by `2`

is less than `0.5`

.

### whenmod

`Type: whenmod :: Int -> Int -> (Pattern a -> Pattern a) -> Pattern a -> Pattern a`

`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`

:

`d1 $ whenmod 8 4 (fast 2) (sound "bd sn kurt")`

### ifp

`Type: ifp :: (Int -> Bool) -> (Pattern a -> Pattern a) -> (Pattern a -> Pattern a) -> Pattern a -> Pattern a`

`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:

`d1 $ ifp ((== 0).(flip mod 2))`

(striate 4)

(# coarse "24 48") $

sound "hh hc"

This will apply `striate 4`

for every even cycle, and `# coarse "24 48"`

for every odd one.

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`

.

## Conditions on ControlPatterns

### fix

`Type: fix :: (ControlPattern -> ControlPattern) -> ControlPattern -> ControlPattern -> ControlPattern`

The `fix`

function applies another function to matching events in a pattern of controls. `fix`

is `contrast`

where the false-branching function is set to the identity `id`

.

For example:

`d1 $ slow 2 $ fix (# crush 3) (n "[1,4]") $ n "0 1 2 3 4 5 6" # sound "arpy"`

The above only adds the `crush`

control when the `n`

control is set to either `1`

or `4`

.

You can be quite specific, for example

`fix (hurry 2) (s "drum" # n "1")`

to apply the function `hurry 2`

to sample `1`

of the drum sample set, and leave the rest as they are.

### unfix

`unfix`

is `fix`

but only applies when the testing pattern is *not* a match.

### contrast

`Type: contrast :: (ControlPattern -> ControlPattern) -> (ControlPattern -> ControlPattern) -> ControlPattern -> ControlPattern -> ControlPattern`

`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:

`d1 $ contrast (|+ n 12) (|- n 12) (n "c") $ n (run 4) # s "superpiano"`

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:

`d1 $ contrast (|+ n 12) (|- n 12) (s "<superpiano superchip>") $ s "superpiano superchip" # n 0`

If you listen to this you'll hear that which instrument is shifted up and which instrument is shifted down alternates between cycles.

### contrastBy

`Type: contrastBy :: (a -> Value -> Bool) -> (ControlPattern -> Pattern b) -> (ControlPattern -> Pattern b) -> Pattern (Map.Map String a) -> Pattern (Map.Map String Value) -> Pattern b`

`contrastBy`

is a more general version of `contrast`

where you can specify an abritrary boolean function that will be used to compare the control patterns. For example, `contrast`

itself is defined as `contrastBy (==)`

, to test for equality.

Compare the following:

`d1 $ contrast (|+ n 12) (|- n 12) (n "2") $ n "0 1 2 [3 4]" # s "superpiano"`

d2 $ contrastBy (>=) (|+ n 12) (|- n 12) (n "2") $ n "0 1 2 [3 4]" # s "superpiano"

In the latter example, we test for "greater than or equals to" instead of simple equality.

## Choosing patterns and functions

### choose

`Type: choose :: [a] -> Pattern a`

The `choose`

function emits a stream of randomly choosen values from the given list, as a continuous pattern:

`d1 $ sound "drum ~ drum drum" # n (choose [0,2,3])`

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

`Type: chooseBy :: Pattern Double -> [a] -> Pattern a`

The `chooseBy`

function is like choose but instead of selecting elements of the list randomly, it uses the given pattern to select elements.

`chooseBy "0 0.25 0.5" ["a","b","c","d"]`

will result in the pattern `"a b c" `

.

### wchoose

`Type: wchoose :: [(a, Double)] -> Pattern a`

`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`

.

`d1 $ sound "drum ~ drum drum" # n (wchoose [(0,0.25),(2,0.5),(3,0.25)])`

Prior to version `1.0.0`

of **Tidal**, the weights had to add up to `1`

, but this is no longer the case.

### wchooseby

`Type: wchooseBy :: Pattern Double -> [(a,Double)] -> Pattern a`

The `wchooseBy`

function is like `wchoose`

but instead of selecting elements of the list randomly, it uses the given pattern to select elements.

### select

`select :: Pattern Double -> [Pattern a] -> Pattern a`

Chooses between a list of patterns, using a pattern of floats (from `0`

to `1`

).

### selectF

`selectF :: Pattern Double -> [Pattern a -> Pattern a] -> Pattern a -> Pattern a`

Chooses between a list of functions, using a pattern of floats (from `0`

to `1`

)

### pickF

`pickF :: Pattern Int -> [Pattern a -> Pattern a] -> Pattern a -> Pattern a`

Chooses between a list of functions, using a pattern of integers.

### squeeze

`squeeze :: Pattern Int -> [Pattern a] -> Pattern a`

Chooses between a list of patterns, using a pattern of integers.

### inhabit

`inhabit :: [(String, Pattern a)] -> Pattern String -> Pattern a`

`inhabit`

allows you to link patterns to some String, or in other words, to give patterns a name and then call them from within another pattern of Strings.

For example, we may make our own bassdrum, hi-hat and snaredrum kit using tidal:

`do`

let drum = inhabit [("bd",s "sine" |- accelerate 1.5),("hh",s "alphabet:7" # begin 0.7 # hpf 7000),("sd",s "invaders:3" # speed 12)]

d1 $ drum "[bd*8?, [~hh]*4, sd(6,16)]"

`inhabit`

can be very useful when using MIDI controlled drum machines, since you can give understandable drum names to patterns of notes.

## Boolean conditions

### struct

`Type: struct :: Pattern Bool -> Pattern a -> Pattern a`

`struct`

places a rhythmic 'boolean' structure on the pattern you give it. For example:

`d1 $ struct ("t ~ t*2 ~") $ sound "cp"`

... is the same as ...

`d1 $ sound "cp ~ cp*2 ~"`

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:

`d1 $ struct ("t f t*2 f") $ sound "cp"`

These true/false binary patterns become useful when you conditionally manipulate them, for example 'inverting' the values using `every`

and `inv`

:

`d1 $ struct (every 3 inv "t f t*2 f") $ sound "cp"`

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:

`d1 $ struct (every 3 inv "t(3,8)") $ sound "cp"`

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

`Type: mask :: Pattern Bool -> Pattern a -> Pattern a`

`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:

`d1 $ sound (cat ["sn*8", "[cp*4 bd*4, hc*5]"]) # n (run 8)`

If we apply a mask to it:

`d1 $ mask "t t t ~ t t ~ t"`

$ s (cat ["sn*8", "[cp*4 bd*4, bass*5]"])

# n (run 8)

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:

`d1 $ mask "1 ~ 1 ~ 1 1 ~ 1"`

$ s (cat ["can*8", "[cp*4 sn*4, jvbass*16]"])

# n (run 8)

### sew

`Type: Pattern Bool -> Pattern a -> Pattern a -> Pattern a`

`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.

`d1 $ sound (sew "t f" "bd*8" "cp*8")`

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:

`d1 $ sew "t <f t> <f [f t] t>" (n "0 .. 15" # s "future") (s "cp:3*16" # speed saw + 1.2)`

You can also use Euclidean rhythm syntax in the boolean sequence:

`d1 $ sew "t(11,16)" (n "0 .. 15" # s "future") (s "cp:3*16" # speed sine + 1.5)`

### stitch

`Type: Pattern Bool -> Pattern a -> Pattern a -> Pattern a`

`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:

`d1 $ ccv (stitch "t(7,16)" 127 0) # ccn 0 # "midi"`

## Euclidians

### euclid

`Type: euclid :: Pattern Int -> Pattern Int -> Pattern a -> Pattern a`

`euclid`

creates a Euclidean rhythmic structure. It produces the same output as the Euclidean pattern string. For example:

`d1 $ euclid 3 8 $ sound "cp"`

is the same as:

`d1 $ sound "cp(3,8)"`

`euclid`

accepts two parameters that can be patterns:

`d1 $ euclid "<3 5>" "[8 16]/4" $ s "bd"`

### euclidInv

`Type: euclidInv :: Pattern Int -> Pattern Int -> Pattern a -> Pattern a`

Inverts the pattern given by `euclid`

. For example:

`d1 $ stack [euclid 5 8 $ s "bd",`

euclidInv 5 8 $ s "hh27"]

to hear that the hi-hat event fires on every one of the eight even beats that the bass drum does not.

### euclidFull

`Type: euclidFull :: Pattern Int -> Pattern Int -> Pattern a -> Pattern a ->Pattern a`

`euclidFull`

is a convenience function for playing one pattern on the euclidean rhythm and a different pattern on the off-beat.

`euclidFull 5 8 (s "bd") (s "hh27")`

is equivalent to our above example.

## ControlPattern conditions

### fix

`Type: fix :: (ControlPattern -> ControlPattern) -> ControlPattern -> ControlPattern -> ControlPattern`

With `fix`

you can apply a ControlPattern as a condition and apply a function wich matches the controls. The first parameter is the function to apply and the second paramete is the condition.

`d1 $ fix (ply 2) (s "hh") $ s "bd hh sn hh"`

### fixRange

`fixRange :: (ControlPattern -> Pattern ValueMap) -> Pattern (Map.Map String (Value, Value)) -> ControlPattern -> ControlPattern`

The `fixRange`

function isn't very user-friendly at the moment but you can create a `fix`

variant with a range condition. Any value of a ControlPattern wich matches the values will apply the passed function.

`d1 $ (fixRange ((# distort 1) . (# gain 0.8)) (pure $ Map.singleton "note" ((VN 0, VN 7)))) $ s "superpiano" <| note "1 12 7 11"`

## ifp

`Type: ifp :: (Int -> Bool) -> (Pattern a -> Pattern a) -> (Pattern a -> Pattern a) -> Pattern a -> Pattern a`

`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:

`d1 $ ifp ((== 0).(flip mod 2))`

(striate 4)

(# coarse "24 48") $

sound "hh hc"

This will apply `striate 4`

for every even cycle, and `# coarse "24 48"`

for every odd one.

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`

.