Alteration
This page will present you all the functions that can be used to manipulate and alter 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.
Scaling
range
Type: range :: Num a => Pattern a -> Pattern a -> Pattern a -> Pattern a
range will take a pattern which goes from 0 to 1 (such as sine), and scale it to a different range - between the first and second arguments. In the below example, range 1 1.5 shifts the range of sine from 0 - 1 to 1 - 1.5.
d1 $ jux (iter 4) $ sound "arpy arpy:2*2"
|+ speed (slow 4 $ range 1 1.5 sine)
The above is equivalent to the following:
d1 $ jux (iter 4) $ sound "arpy arpy:2*2"
|+ speed (slow 4 $ sine * 0.5 + 1)
rangex
Type: rangex :: (Floating b, Functor f) => b -> b -> f b -> f b
rangex is an exponential version of range described above, good to use for frequencies. For example, range 20 2000 "0.5" will give 1010 - halfway between 20 and 2000. But rangex 20 2000 0.5 will give 200 - halfway between on a logarithmic scale. This usually sounds better if you’re using the numbers as pitch frequencies. Since rangex uses logarithms, don’t try to scale things to zero or less!
quantise
Type: quantise :: (Functor f, RealFrac b) => b -> f b -> f b
quantise is useful for rounding a collection of numbers to some particular base fraction. For example,
quantise 5 [0, 1.3 ,2.6,3.2,4.7,5]
It will round all the values to the nearest (1/5)=0.2 and thus will output the list [0.0,1.2,2.6,3.2,4.8,5.0]. You can use this function to force a continuous pattern like sine into specific values. In the following example:
d1 $ s "superchip*8" # n (quantise 1 $ range (-10) (10) $ slow 8 $ cosine)
# release (quantise 5 $ slow 8 $ sine + 0.1)
all the releases selected be rounded to the nearest 0.1 and the notes selected to the nearest 1.
quantise with fractional inputs does the consistent thing: quantise 0.5 rounds values to the nearest 2, quantise 0.25 rounds the nearest 4, etc...
Degrade
degrade
Type: degrade :: Pattern a -> Pattern a
degrade randomly removes events from a pattern, 50% of the time. Example usage:
d1 $ slow 2 $ degrade $ sound "[[[feel:5*8,feel*3] feel:3*8], feel*4]"
# accelerate "-6"
# speed "2"
degradeBy
Type: degradeBy :: Double -> Pattern a -> Pattern a
Similarly to degrade, degradeBy allows you to control the percentage of events that are removed. For example, to remove events 90% of the time:
d1 $ slow 2 $ degradeBy 0.9 $ sound "[[[feel:5*8,feel*3] feel:3*8], feel*4]"
# accelerate "-6"
# speed "2"
unDegradeBy
Type: unDegradeBy :: Double -> Pattern a -> Pattern a
unDegradeBy is degradeBy but with the percentage describing how many events to keep on average not remove.
Repetitions
ply
Type: ply :: Pattern Int -> Pattern a -> Pattern a
The ply function repeats each event the given number of times. For example:
d1 $ ply 3 $ s "bd ~ sn cp"
... is equivalent to ...
d1 $ s "[bd bd bd] ~ [sn sn sn] [cp cp cp]"
The first parameter may be given as a pattern, so that:
d1 $ ply "2 3" $ s "bd ~ sn cp"
... is equivalent to ...
d1 $ s "[bd bd] ~ [sn sn sn] [cp cp cp]"
Here is an example of it being used conditionally:
d1 $ every 3 (ply 4) $ s "bd ~ sn cp"
stutter
Type: stutter :: Integral i => i -> Time -> Pattern a -> Pattern a
stutter is like stut that doesn't reduce the volume or ply if you controlled the timing. stutter n t repeats each event in the pattern n times, separated by t time (in fractions of a cycle).
d1 $ stutter 4 (1/16) $ s "bd cp"
is functionally equivalent to ...
d1 $ stut 4 1 (1/16) $ s "bd cp"
Specific conveniences functions that use stutter are:
echo = stutter (2 :: Int)
triple = stutter (3 :: Int)
quad = stutter (4 :: Int)
double = echo
stripe
Type: stripe :: Pattern Int -> Pattern a -> Pattern a
The stripe function repeats a pattern at random speeds. The first parameter gives the number of cycles to operate over, for example stripe 2 will repeat a pattern twice, over two cycles. Each cycle will be played at a random speed, but in such a way that the total duration will be the same.
For example in the following example, the start of every third repetition of the d1 pattern will match with the clap on the d2 pattern.
d1 $ stripe 3 $ sound "bd sd ~ [mt ht]"
d2 $ sound "cp"
slowstripe
Type: slowstripe :: Pattern Int -> Pattern a -> Pattern a
The slowstripe function is the same as stripe but the result is also slowed down by n time (where n is the first parameter of the function. This means that the mean average duration of the stripes is exactly one cycle, and every nth stripe starts on a cycle boundary (in indian classical terms, the sam). Usage:
d1 $ slowstripe 3 $ sound "bd sd ~ [mt ht]"
d2 $ sound "cp"
palindrome
Type: palindrome :: Pattern a -> Pattern a
The palindrome function applies rev to a pattern every other cycle, so that the pattern alternates between forwards and backwards. For example this:
d1 $ palindrome $ sound "arpy:0 arpy:1 arpy:2 arpy:3"
... is the same as this:
d1 $ slow 2 $ sound "arpy:0 arpy:1 arpy:2 arpy:3 arpy:3 arpy:2 arpy:1 arpy:0"
... and indeed this:
d1 $ every 2 rev $ sound "arpy:0 arpy:1 arpy:2 arpy:3"
Truncation
trunc
Type: trunc :: Pattern Time -> Pattern a -> Pattern a
trunc truncates a pattern so that only a fraction of the pattern is played. The following example plays only the first three quarters of the pattern:
d1 $ trunc 0.75 $ sound "bd sn*2 cp hh*4 arpy bd*2 cp bd*2"
You can also pattern the first parameter, for example to cycle through three values, one per cycle:
d1 $ trunc "<0.75 0.25 1>" $ sound "bd sn:2 [mt rs] hc"
linger
Type: linger :: Pattern Time -> Pattern a -> Pattern a
linger is similar to trunc, in that it truncates a pattern so that only the first fraction of the pattern is played. However unlike trunc, linger repeats that part to fill the remainder of the cycle.
For example this repeats the first quarter, so you only hear a single repeating note:
d1 $ linger 0.25 $ n "0 2 [3 4] 2" # sound "arpy"
or slightly more interesting, applied only every fourth cycle:
d1 $ every 4 (linger 0.25) $ n "0 2 [3 4] 2" # sound "arpy"
or to a chopped-up sample:
d1 $ every 2 (linger 0.25) $ loopAt 2 $ chop 8 $ sound "breaks125"
You can also pattern the first parameter, for example to cycle through three values, one per cycle:
d1 $ linger "<0.75 0.25 1>" $ sound "bd sn:2 [mt rs] hc"
d1 $ linger "<0.25 0.5 1>" $ loopAt 2 $ chop 8 $ sound "breaks125"
chunk
Type: chunk :: Int -> (Pattern b -> Pattern b) -> Pattern b -> Pattern b
chunk 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). Example:
d1 $ chunk 4 (# speed 2) $ sound "bd hh sn cp"
The below highlights in uppercase which part of the above pattern has the (# speed 2) function applied to it over four cycles:
BD hh sn cp
bd HH sn cp
bd hh SN cp
bd hh sn CP
Another example:
d1 $ chunk 4 (hurry 2) $ sound "bd sn:2 [~ bd] sn:2"
chunk'
chunk' does the same as chunk but cycles through the parts in the reverse direction.
loopFirst
loopFirst is a function that takes a pattern and loops only the first cycle of the pattern. For example, in the following code will only play the bass drum sample.
d1 $ loopFirst $ s "<<bd*4 ht*8> cp*4>"
This function combines with sometimes to insert events from the first cycle randomly into subsequent cycles of the pattern:
d1 $ sometimes loopFirst $ s "<<bd*4 ht*8> cp*4>"
Shuffling and scrambling
bite
Type: bite :: Int -> Pattern Int -> Pattern a -> Pattern a
The bite function allows you to slice each cycle into a given number of equal sized bits, and then pattern those bits by number. It's similar to slice, but is for slicing up patterns, rather than samples. The following slices the pattern into four bits, and then plays those bits in turn.
d1 $ bite 4 "0 1 2 3" $ n "0 .. 7" # sound "arpy"
Of course that doesn't actually change anything, but then you can reorder those bits:
d1 $ bite 4 "2 0 1 3" $ n "0 .. 7" # sound "arpy"
The slices bits of pattern will be squeezed or contracted to fit:
d1 $ bite 4 "2 [0 3] 1*4 1" $ n "0 .. 7" # sound "arpy"
shuffle
Type: shuffle :: Int -> Pattern a -> Pattern a
shuffle takes a number and a pattern as input, divides the pattern into the given number of parts, and returns a new pattern as a random permutation of the parts, picking one of each per cycle. This could also be called "sampling without replacement". For example:
d1 $ sound $ shuffle 3 "bd sn hh"
... will sometimes play "sn bd hh" or "hh sn bd", but will never play "bd sn bd" or "hh hh hh", because that isn't a permutation of the three parts.
scramble
Type: scramble :: Int -> Pattern a -> Pattern a
scramble takes a number and a pattern as input, divides the pattern into the given number of parts, and returns a new pattern by randomly selecting from the parts. This could also be called "sampling with replacement". For example:
d1 $ sound $ scramble 3 "bd sn hh"
... will sometimes play "sn bd hh" or "hh sn bd", but can also play "bd sn bd" or "hh hh hh", because it can make any random combination of the three parts.
rot
Type: rot :: Ord a => Pattern Int -> Pattern a -> Pattern a
The rot function 'rotates' the values in a pattern, while preserving its structure. For example in the following, each value will shift to its neighbour's position one step to the left, so that b takes the place of a, a of c, and c of b:
rot 1 "a ~ b c"
The result is equivalent of:
"b ~ c a"
The first parameter is the number of steps, and may be given as a pattern, for example:
d1 $ rot "<0 0 1 3>" $ n "0 ~ 1 2 0 2 ~ 3*2" # sound "drum"
The above will not rotate the pattern for the first two cycles, will rotate it by one the third cycle, and by three the fourth cycle.
Step sequencers
step
Type: step :: String -> String -> Pattern String
step acts as a kind of simple step-sequencer using strings. For example, step "sn" "x x 12 " is equivalent to the pattern of strings given by "sn ~ sn ~ sn:1 sn:2 ~". step substitutes the given string for each x, for each number it substitutes the string followed by a colon and the number, and for everything else it puts in a rest.
In other words, step generates a pattern of strings in exactly the syntax you'd want for selecting samples and that can be fed directly into the s function.
d1 $ s (step "sn" "x x 12 ")
step'
Type: step' :: [String] -> String -> Pattern String
step' is like step but more general, using the numbers in the step-sequencing string as indexes into the list of strings you give it.
d1 $ s (step' ["superpiano","supermandolin"] "0 1 000 1") # sustain 4 # n 0
is equivalent to
d1 $ s "superpiano ~ supermandolin ~ superpiano!3 ~ supermandolin" # sustain 4 # n 0
There is also steps. You can take a look at this function in the Accumulation section
lindenmayer
Type: Num b => Int -> String -> String -> [b]
lindenmayer takes an integer b, a Lindenmayer system rule set and an initiating string as input in order to generate an L-system tree string of b iterations. It can be used in conjunction with a step function to convert the generated string into a playable pattern. For example:
d1 $ slow 16 $ sound $ step' ["feel:0", "sn:1", "bd:0"]
(take 512 $ lindenmayer 5 "0:1~~~,1:0~~~2~~~~~0~~~2~,2:2~1~,~:~~1~"
"0")
... generates an L-system with initiating string "0" and maps it onto a list of samples.
Complex L-system trees with many rules and iterations can sometimes result in unwieldy strings. Using take n to only use the first n elements of the string, along with a slow function, can make the generated values more manageable.
Higher-order
spread
Type: spread :: (a -> t -> Pattern b) -> [a] -> t -> Pattern b
The spread function allows you to take a pattern transformation which takes a parameter, such as slow, and provide several parameters which are switched between. In other words it 'spreads' a function across several values. Taking a simple high hat loop as an example:
d1 $ sound "ho ho:2 ho:3 hc"
We can speed it up by different amounts, such as by 2x:
d1 $ fast 2 $ sound "ho ho:2 ho:3 hc"
Or by 3x:
d1 $ fast 3 $ sound "ho ho:2 ho:3 hc"
But if we use spread, we can make a pattern which alternates between the two speeds:
d1 $ spread fast[2,3] $ sound "ho ho:2 ho:3 hc"
Note that many functions now allow pattern input. This is equivalent to the above:
d1 $ fast "<2 3>" $ sound "ho ho:2 ho:3 hc"
Note that if you pass ($) as the function to spread values over, you can put different functions as the list of values. For example:
d1 $ spread ($) [density 2, rev, slow 2, striate 3, (# speed "0.8")] $ sound "[bd*2 [~ bd]] [sn future]*2 cp jvbass*4"
Above, the pattern will have these transforms applied to it, one at a time, per cycle:
cycle 1: density 2 - pattern will increase in speed
cycle 2: rev - pattern will be reversed
cycle 3: slow 2 - pattern will decrease in speed
cycle 4: striate 3 - pattern will be granualized
cycle 5: (# speed "0.8") - pattern samples will be played back more slowly
After (# speed "0.8"), the transforms will repeat and start at density 2 again.
(This is the same as slowspread in earlier versions of TidalCycles.)
spreadf
A convenient shorthand for spread ($).
fastspread
fastspread works the same as spread, but the result is squashed into a single cycle. If you gave four values to spread, then the result would seem to speed up by a factor of four. Compare these two:
d1 $ spread ($) [gap 4, striate 4] $ sound "ho ho:2 ho:3 hc"
d1 $ fastspread ($) [gap 4, striate 4] $ sound "ho ho:2 ho:3 hc"
spreadChoose
spreadChoose (alias spreadr) works the same as spread, but the values are selected at random, one cycle at a time. For example:
d1 $ spreadChoose ($) [gap 4, striate 4] $ sound "ho ho:2 ho:3 hc"