Sound.Tidal.Context

approxRational, applied to two real fractional numbers x and epsilon, returns the simplest rational number within epsilon of x. A rational number y is said to be simpler than another y' if

• abs (numerator y) <= abs (numerator y'), and

• denominator y <= denominator y'.

Any real interval contains a unique simplest rational; in particular, note that 0/1 is the simplest rational of all.

Forms the ratio of two integral numbers.

Extract the denominator of the ratio in reduced form: the numerator and denominator have no common factor and the denominator is positive.

Extract the numerator of the ratio in reduced form: the numerator and denominator have no common factor and the denominator is positive.

chop granularises every sample in place as it is played, turning a pattern of samples into a pattern of sample parts. Can be used to explore granular synthesis.

Use an integer value to specify how many granules each sample is chopped into:

d1 $ chop 16 $ sound "arpy arp feel*4 arpy*4"

Different values of chop can yield very different results, depending on the samples used:

d1 $ chop 16 $ sound (samples "arpy*8" (run 16))
d1 $ chop 32 $ sound (samples "arpy*8" (run 16))
d1 $ chop 256 $ sound "bd*4 [sn cp] [hh future]*2 [cp feel]"

You can also use chop (or striate) with very long samples to cut them into short chunks and pattern those chunks. The following cuts a sample into 32 parts, and plays it over 8 cycles:

d1 $ loopAt 8 $ chop 32 $ sound "bev"

The loopAt takes care of changing the speed of sample playback so that the sample fits in the given number of cycles perfectly. As a result, in the above the granules line up perfectly, so you can’t really hear that the sample has been cut into bits. Again, this becomes more apparent when you do further manipulations of the pattern, for example rev to reverse the order of the cut up bits:

d1 $ loopAt 8 $ rev $ chop 32 $ sound "bev"

Ceiling trigger. Aligns the start of a pattern to the next cycle boundary, just like qtrigger.

Applies a type of delay to a pattern. It has three parameters, which could be called depth, time and feedback. depth is and integer, and time and feedback are floating point numbers.

This adds a bit of echo:

d1 $ echo 4 0.2 0.5 $ sound "bd sn"

The above results in 4 echos, each one 50% quieter than the last, with 1/5th of a cycle between them.

It is possible to reverse the echo:

d1 $ echo 4 (-0.2) 0.5 $ sound "bd sn"

echoWith is similar to echo, but instead of just decreasing volume to produce echoes, echoWith applies a function each step and overlays the result delayed by the given time.

d1 $ echoWith 2 "1%3" (# vowel "{a e i o u}%2") $ sound "bd sn"

In this case there are two _overlays_ delayed by 1/3 of a cycle, where each has the vowel filter applied.

d1 $ echoWith 4 (1/6) (|* speed "1.5") $ sound "arpy arpy:2"

In the above, three versions are put on top, with each step getting higher in pitch as |* speed "1.5" is successively applied.

Floor trigger. Aligns the start of a pattern to the previous cycle boundary.

gap is similar to chop in that it granualizes every sample in place as it is played, but every other grain is silent. Use an integer value to specify how many granules each sample is chopped into:

d1 $ gap 8 $ sound "jvbass"
d1 $ gap 16 $ sound "[jvbass drum:4]"

hurry is similiar to fast in that it speeds up a pattern, but it also increases the speed control by the same factor. So, if you’re triggering samples, the sound gets higher in pitch. For example:

d1 $ every 2 (hurry 2) $ sound "bd sn:2 ~ cp"

(A function that takes two ControlPatterns, and blends them together into a new ControlPattern. An ControlPattern is basically a pattern of messages to a synthesiser.)

Shifts between the two given patterns, using distortion.

Example:

d1 $ interlace (sound  "bd sn kurt") (every 3 rev $ sound  "bd sn:2")

loopAt makes a sample fit the given number of cycles. Internally, it works by setting the unit parameter to "c", changing the playback speed of the sample with the speed parameter, and setting setting the density of the pattern to match.

d1 $ loopAt 4 $ sound "breaks125"

It’s a good idea to use this in conjuction with chop, so the break is chopped into pieces and you don’t have to wait for the whole sample to start/stop.

d1 $ loopAt 4 $ chop 32 $ sound "breaks125"

Like all Tidal functions, you can mess about with this considerably. The below example shows how you can supply a pattern of cycle counts to loopAt:

d1 $ juxBy 0.6 (|* speed "2")
   $ slowspread (loopAt) [4,6,2,3]
   $ chop 12
   $ sound "fm:14"

Turns a pattern of milliseconds into a pattern of (rational) cycle durations, according to the current cps.

Alias for mtrigger.

(Alias mt) Mod trigger. Aligns the start of a pattern to the next cycle boundary where the cycle is evenly divisible by a given number. qtrigger is equivalent to mtrigger 1.

In the following example, when activating the d1 pattern, it will start at the same time as the next clap, even if it has to wait for 3 cycles. Once activated, the arpy sound will play on every cycle, just like any other pattern:

do
  resetCycles
  d2 $ every 4 (# s "clap") $ s "bd"

d1 $ mtrigger 4 $ filterWhen (>=0) $ s "arpy"

Alias for qtrigger.

(Alias qt) Quantise trigger. Aligns the start of the pattern with the next cycle boundary. For example, this pattern will fade in starting with the next cycle after the pattern is evaluated:

d1 $ qtrigger $ s "hh(5, 8)" # amp envL

Note that the pattern will start playing immediately. The start of the pattern aligns with the next cycle boundary, but events will play before if the pattern has events at negative timestamps (which most loops do). These events can be filtered out, for example:

d1 $ qtrigger $ filterWhen (>= 0) $ s "hh(5, 8)"

Alternatively, you can use wait to achieve the same result:

wait 1 1 $ s "bd hh hh hh"

randslice chops the sample into the given number of pieces and then plays back a random one each cycle:

d1 $ randslice 32 $ sound "bev"

Use fast to get more than one per cycle:

d1 $ fast 4 $ randslice 32 $ sound "bev"

Rounded trigger. Aligns the start of a pattern to the nearest cycle boundary, either next or previous.

Turns a pattern of seconds into a pattern of (rational) cycle durations

slice is similar to chop and striate, in that it’s used to slice samples up into bits. The difference is that it allows you to rearrange those bits as a pattern.

d1 $ slice 8 "7 6 5 4 3 2 1 0"
   $ sound "breaks165"
   # legato 1

The above slices the sample into eight bits, and then plays them backwards, equivalent of applying rev $ chop 8. Here’s a more complex example:

d1 $ slice 8 "[<0*8 0*2> 3*4 2 4] [4 .. 7]"
   $ sound "breaks165"
   # legato 1

smash is a combination of spread and striate — it cuts the samples into the given number of bits, and then cuts between playing the loop at different speeds according to the values in the list. So this:

d1 $ smash 3 [2,3,4] $ sound "ho ho:2 ho:3 hc"

is a bit like this:

d1 $ spread (slow) [2,3,4] $ striate 3 $ sound "ho ho:2 ho:3 hc"

This is quite dancehall:

d1 $ ( spread' slow "1%4 2 1 3"
     $ spread (striate) [2,3,4,1]
     $ sound "sn:2 sid:3 cp sid:4"
     )
   # speed "[1 2 1 1]/2"

An altenative form of smash, which uses chop instead of striate.

Compare the following variations:

d1 $ smash 6 [2,3,4] $ sound "ho ho:2 ho:3 hc"
d1 $ smash' 6 [2,3,4] $ sound "ho ho:2 ho:3 hc"
d1 $ smash 12 [2,3,4] $ s "bev*4"
d1 $ smash' 12 [2,3,4] $ s "bev*4"

spin will "spin" and layer up a pattern the given number of times, with each successive layer offset in time by an additional 1/n of a cycle, and panned by an additional 1/n. The result is a pattern that seems to spin around. This function work well on multichannel systems.

d1 $ slow 3
   $ spin 4
   $ sound "drum*3 tabla:4 [arpy:2 ~ arpy] [can:2 can:3]"

splice is similar to slice, but the slices are automatically pitched up or down to fit their ‘slot’.

d1 $ splice 8 "[<0*8 0*2> 3*4 2 4] [4 .. 7]" $ sound "breaks165"

Striate is a kind of granulator, cutting samples into bits in a similar to chop, but the resulting bits are organised differently. For example:

d1 $ striate 3 $ sound "ho ho:2 ho:3 hc"

This plays the loop the given number of times, but triggers progressive portions of each sample. So in this case it plays the loop three times, the first time playing the first third of each sample, then the second time playing the second third of each sample, and lastly playing the last third of each sample. Replacing striate with chop above, one can hear that the 'chop version plays the bits from each chopped-up sample in turn, while striate "interlaces" the cut up bits of samples together.

You can also use striate with very long samples, to cut them into short chunks and pattern those chunks. This is where things get towards granular synthesis. The following cuts a sample into 128 parts, plays it over 8 cycles and manipulates those parts by reversing and rotating the loops:

d1 $  slow 8 $ striate 128 $ sound "bev"

DEPRECATED, use striateBy instead.

The striateBy function is a variant of striate with an extra parameter which specifies the length of each part. The striateBy function still scans across the sample over a single cycle, but if each bit is longer, it creates a sort of stuttering effect. For example the following will cut the bev sample into 32 parts, but each will be 1/16th of a sample long:

d1 $ slow 32 $ striateBy 32 (1/16) $ sound "bev"

Note that striate and striateBy use the begin and end parameters internally. This means that you probably shouldn't also specify begin or end.

DEPRECATED, use echo instead

DEPRECATED, use echoWith instead

DEPRECATED, use echoWith instead

Align the start of a pattern with the time a pattern is evaluated, rather than the global start time. Because of this, the pattern will probably not be aligned to the pattern grid.

This aligns the start of a pattern to some value relative to the time the pattern is evaluated. The provided function maps the evaluation time (on the global cycle clock) to a new time, and then triggerWith aligns the pattern's start to the time that's returned.

This is a more flexible triggering function. In fact, all the other trigger functions are defined based on triggerWith. For example, trigger is just triggerWith id.

In the next example, use d1 as a metronome, and play with different values (from 0 to 1) on the const expression. You’ll notice how the clap is displaced from the beginning of each cycle to the end, as the number increases:

d1 $ s "bd hh!3"

d2 $ triggerWith (const 0.1) $ s "clap"

This last example is equivalent to this:

d2 $ rotR 0.1 $ s "clap"

weave applies one control pattern to a list of other control patterns, with a successive time offset. It uses an OscPattern to apply the function at different levels to each pattern, creating a weaving effect. For example:

d1 $ weave 16 (pan sine)
     [ sound "bd sn cp"
     , sound "casio casio:1"
     , sound "[jvbass*2 jvbass:2]/2"
     , sound "hc*4"
     ]

In the above, the pan sine control pattern is slowed down by the given number of cycles, in particular 16, and applied to all of the given sound patterns. What makes this interesting is that the pan control pattern is successively offset for each of the given sound patterns; because the pan is closed down by 16 cycles, and there are four patterns, they are ‘spread out’, i.e. with a gap of four cycles. For this reason, the four patterns seem to chase after each other around the stereo field. Try listening on headphones to hear this more clearly.

You can even have it the other way round, and have the effect parameters chasing after each other around a sound parameter, like this:

d1 $ weave 16 (sound "arpy" >| n (run 8))
     [ vowel "a e i"
     , vowel "i [i o] o u"
     , vowel "[e o]/3 [i o u]/2"
     , speed "1 2 3"
     ]

An old alias for weaveWith.

weaveWith is similar to the above, but weaves with a list of functions, rather than a list of controls. For example:

d1 $ weaveWith 3 (sound "bd [sn drum:2*2] bd*2 [sn drum:1]")
     [ fast 2
     , (# speed "0.5")
     , chop 16
     ]

Shifts a pattern back in time by the given amount, expressed in cycles

Alternate between cycles of the two given patterns > d1 $ append (sound "bd*2 sn") (sound "arpy jvbass*2")

Like append, but for a list of patterns. Interlaces them, playing the first cycle from each in turn, then the second cycle from each, and so on. It concatenates a list of patterns into a new pattern; each pattern in the list will maintain its original duration. For example:

d1 $ cat [sound "bd*2 sn", sound "arpy jvbass*2"]
d1 $ cat [sound "bd*2 sn", sound "arpy jvbass*2", sound "drum*2"]
d1 $ cat [sound "bd*2 sn", sound "jvbass*3", sound "drum*2", sound "ht mt"]

compress takes a pattern and squeezes it within the specified time span (i.e. the ‘arc’). The new resulting pattern is a sped up version of the original.

d1 $ compress (1/4, 3/4) $ s "[bd sn]!"

In the above example, the pattern will play in an arc spanning from 25% to 75% of the duration of a cycle. It is equivalent to:

d1 $ s "~ [bd sn]! ~"

Another example, where all events are different:

d1 $ compress (1/4, 3/4) $ n (run 4) # s "arpy"

It differs from zoom in that it preserves the original pattern but it speeds up its events so to match with the new time period.

cosine - unipolar cosine wave. A pattern of continuous values following a cosine with frequency of one cycle, and amplitude from 0 to 1. Equivalent to 0.25 ~> sine.

cosine2 - bipolar cosine wave. A pattern of continuous values following a cosine with frequency of one cycle, and amplitude from -1 to 1. Equivalent to 0.25 ~> sine2.

An alias for fastGap

'Equal power' version of env, for gain-based transitions

Equal power reversed

envL is a Pattern of continuous Double values, representing a linear interpolation between 0 and 1 during the first cycle, then staying constant at 1 for all following cycles. Possibly only useful if you're using something like the retrig function defined in tidal.el.

like envL but reversed.

• Higher order functions

Functions which work on other functions (higher order functions)

every n f p applies the function f to p, but only affects every n cycles.

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 requires additional parameters itself (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' n o f p is like every n f p but with an offset of o cycles.

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"

Like append, but twice as fast > d1 $ fastAppend (sound "bd*2 sn") (sound "arpy jvbass*2")

The same as cat, but speeds up the result by the number of patterns there are, so the cycles from each are squashed to fit a single cycle.

d1 $ fastcat [sound "bd*2 sn", sound "arpy jvbass*2"]
d1 $ fastcat [sound "bd*2 sn", sound "arpy jvbass*2", sound "drum*2"]
d1 $ fastcat [sound "bd*2 sn", sound "jvbass*3", sound "drum*2", sound "ht mt"]

Turns a list of values into a pattern, playing all of them per cycle. The following are equivalent:

d1 $ n (fastFromList [0, 1, 2]) # s "superpiano"
d1 $ n "[0 1 2]" # s "superpiano"

fastGap is similar to fast but maintains its cyclic alignment, i.e., rather than playing the pattern multiple times, it instead leaves a gap in the remaining space of the cycle. For example, fastGap 2 p would squash the events in pattern p into the first half of each cycle (and the second halves would be empty). The factor should be at least 1.

Alias for fastCat

foldEvery ns f p applies the function f to p, and is applied for each cycle in ns.

It 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 that are multiples 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.

Turns a list of values into a pattern, playing one of them per cycle. The following are equivalent:

d1 $ n (fromList [0, 1, 2]) # s "superpiano"
d1 $ n "<0 1 2>" # s "superpiano"

'fromMaybes; is similar to fromList, but allows values to be optional using the Maybe type, so that Nothing results in gaps in the pattern. The following are equivalent: > d1 $ n (fromMaybes [Just 0, Nothing, Just 2]) # s "superpiano" > d1 $ n "0 ~ 2" # s "superpiano"

isaw like saw, but a descending (inverse) sawtooth.

isaw2 like saw2, but a descending (inverse) sawtooth.

A synonym for fastFromList

Serialises a pattern so there's only one event playing at any one time, making it monophonic. Events which start/end earlier are given priority.

overlay combines two Patterns into a new pattern, so that their events are combined over time. For example, the following two lines are equivalent:

d1 $ sound (overlay "bd sn:2" "cp*3")
d1 $ sound "[bd sn:2, cp*3]"

overlay is equal to <>,

(<>) :: Semigroup a => a -> a -> a

which can thus be used as an infix operator equivalent of overlay:

d1 $ sound ("bd sn:2" <> "cp*3")

A pattern of whole numbers from 0 to the given number, in a single cycle. Can be used used to run through a folder of samples in order:

d1 $ n (run 8) # sound "amencutup"

The first parameter to run can be given as a pattern:

d1 $ n (run "<4 8 4 6>") # sound "amencutup"

saw - unipolar ascending sawtooth wave. A pattern of continuous values following a sawtooth with frequency of one cycle, and amplitude from 0 to 1.

saw2 - bipolar ascending sawtooth wave. A pattern of continuous values following a sawtooth with frequency of one cycle, and amplitude from -1 to 1.

Similar to run, but starts from 1 for the first cycle, successively adds a number until it gets up to n. > d1 $ n (scan 8) # sound "amencutup"

Takes a function of time to values, and turns it into a Pattern. Useful for creating continuous patterns such as sine or perlin.

For example, saw is defined as

saw = sig $ \t -> mod' (fromRational t) 1

sine - unipolar sinewave. A pattern of continuous values following a sinewave with frequency of one cycle, and amplitude from 0 to 1.

sine2 - bipolar sinewave. A pattern of continuous values following a sinewave with frequency of one cycle, and amplitude from -1 to 1.

Alias for append

Alias for cat

Slow down a pattern by the factors in the given time pattern, "squeezing" the pattern to fit the slot given in the time pattern. It is the slow analogue to fastSqueeze.

If the time pattern only has a single value in a cycle, slowSqueeze becomes equivalent to slow. These are equivalent:

d1 $ slow "<2 4>" $ s "bd*8"
d1 $ slowSqueeze "<2 4>" $ s "bd*8"

When the time pattern has multiple values, however, the behavior is a little different. Instead, a slowed version of the pattern will be made for each value in the time pattern, and they’re all combined together in a cycle according to the structure of the time pattern. For example, these are equivalent:

d1 $ slowSqueeze "2 4 8 16" $ s "bd*8"
d1 $ s "bd*4 bd*2 bd bd/2"

as are these:

d1 $ slowSqueeze "2 4 [8 16]" $ s "bd*8"
d1 $ s "bd*4 bd*2 [bd bd/2]"

An alias for slow

square - unipolar square wave. A pattern of continuous values following a square wave with frequency of one cycle, and amplitude from 0 to 1. | square is like sine, for square waves.

square2 - bipolar square wave. A pattern of continuous values following a square wave with frequency of one cycle, and amplitude from -1 to 1.

stack combines a list of Patterns into a new pattern, so that their events are combined over time, i.e., all of the patterns in the list are played simultaneously.

d1 $ stack [
 sound "bd bd*2",
 sound "hh*2 [sn cp] cp future*4",
 sound "arpy" +| n "0 .. 15"
]

This is particularly useful if you want to apply a function or synth control pattern to multiple patterns at once:

d1 $ whenmod 5 3 (striate 3) $ stack [
 sound "bd bd*2",
 sound "hh*2 [sn cp] cp future*4",
 sound "arpy" +| n "0 .. 15"
] # speed "[[1 0.8], [1.5 2]*2]/3"

Similar to fastCat, but each pattern is given a relative duration. You provide proportionate sizes of the patterns to each other for when they’re concatenated into one cycle. The larger the value in the list, the larger relative size the pattern takes in the final loop. If all values are equal then this is equivalent to fastcat (e.g. the following two code fragments are equivalent).

d1 $ fastcat [s "bd*4", s "hh27*8", s "superpiano" # n 0]

d1 $ timeCat [ (1, s "bd*4")
             , (1, s "hh27*8")
             , (1, s "superpiano" # n 0)
             ]

Alias for timeCat

tri - unipolar triangle wave. A pattern of continuous values following a triangle wave with frequency of one cycle, and amplitude from 0 to 1.

tri2 - bipolar triangle wave. A pattern of continuous values following a triangle wave with frequency of one cycle, and amplitude from -1 to 1.

The given pattern transformation is applied only when the given test function returns True. 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.

Like when, but works on continuous time values rather than cycle numbers. The following will apply # speed 2 only when the remainder of the current Time divided by 2 is less than 0.5:

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

Plays a portion of a pattern, specified by a time arc (start and end time). The new resulting pattern is played over the time period of the original pattern.

d1 $ zoom (0.25, 0.75) $ sound "bd*2 hh*3 [sn bd]*2 drum"

In the pattern above, zoom is used with an arc from 25% to 75%. It is equivalent to:

d1 $ sound "hh*3 [sn bd]*2"

Here’s an example of it being used with a conditional:

d1 $ every 4 (zoom (0.25, 0.75)) $ sound "bd*2 hh*3 [sn bd]*2 drum"

Shifts a pattern forward in time by the given amount, expressed in cycles

A pattern of numbers that speed up (or slow down) samples while they play.

In the following example, the sound starts at the original pitch and gets higher as it plays:

d1 $ s "arpy" # accelerate 2

You can use a negative number to make the sound get lower. In this example, a different acceleration is applied to each played note using state values:

d1 $ arp "up" $ note "c'maj'4" # s "arpy" # accelerateTake "susan" [0.2,1,-1]

Controls the amplitude (volume) of the sound. Like gain, but linear. Default value is 0.4.

d1 $ s "arpy" # amp "<0.4 0.8 0.2>"

a pattern of numbers to specify the attack time (in seconds) of an envelope applied to each sample.

a pattern of numbers from 0 to 1. Sets the center frequency of the band-pass filter.

a pattern of anumbers from 0 to 1. Sets the q-factor of the band-pass filter.

A pattern of strings. When sent to SuperDirt, will be prepended to sample folder names, separated by an underscore. This allows sample sets to be organised into separate banks. See https://github.com/musikinformatik/SuperDirt/pull/312

begin receives a pattern of numbers from 0 to 1 and skips the beginning of each sample by the indicated proportion. I.e., 0 would play the sample from the start, 1 would skip the whole sample, and 0.25 would cut off the first quarter.

In this example, the first 3 ade samples are played on every cycle, but the start point from which they are played changes on each cycle:

d1 $ n "0 1 2" # s "ade" # begin "<0 0.25 0.5 0.75>" # legato 1

Spectral binshift

choose the channel the pattern is sent to in superdirt