View source for Tutorial/de


Du hast TidalCycles und (Super)Dirt installiert, vielleicht sogar ein paar Sounds gemacht, aber jetzt bist du bereit, dich an die Arbeit zu machen und wirklich zu lernen wie TidalCycles funktioniert. 
Dieser Leitfaden zeigt Dir wie du von einfachen Pattern zu zu komplexeren Kompositionen kommst. 
Einen schnellen Überblick über die Pattern-Syntax findest du hier:  [[Sequence parser syntax]].

Wir empfehlen Dir den Code während des Lesens direkt auszuprobieren. Mach deine eigenen Experimente, indem du die Beispiele veränderst und herausfindest, wohin Dich das führt. 

= Rhythmische Sequenzen erzeugen =
==Ein einzelnes Sample abspielen==
TidalCycles bietet 16 'Verbindungen' zum SuperDirt Syntheziser  (d1 bis d16)
Diese Verbindungen kannst du Dir wie einzelne Kanäle an einem Mischpult vorstellen.   
Hier mal ein sehr simples Beispiel, mit dem in jedem Cycle eine Kick-Drum abspielt wird:

<source>
 d1 $ sound "bd"
</source>

Führe den Code im Atom (oder Emacs) Editor aus, indem du Ctrl+Enter drückst. 
Wenn du den Sound wieder stoppen möchtest, schau Dir den Abschnitt über das Beenden von Cycles an.

Schauen wir uns den Code genauer an:
Mit <source inline>sound</source> erstellen wir ein Pattern aus Sound-Samples und mit <source inline>"bd"</source> definieren welcher Sound gespielt wird. In diesem Fall wird pro Cycle ein Bassdrum-Sample gespielt.

Bei der Installation von SuperDirt werden auch eine ganze Reihe von Samples mitgeliefert, die du im Dirt-Samples-Ordner finden kannst. Jeder Unterordner hier korrespondiert mit dem Namen eines Samples (wie bd).

Um die SuperDirt-Samples auf deinem System zu finden, wechsle zu SuperCollider und öffne dort über den Menüpunkt 'File' das 'user support-directory'. 
Von dort aus öffne die 
'downloaded- quarks' und darin dann die 'Dirt-Samples'. 
Hier solltest du eine ganze Reihe von Ordnern finden - 
jeder davon enthält eine Sample-Bank mit Standard-WAV-Dateien.
Du kannst natürlich auch neue Ordner erstellen und deine eigenen Sounds hinzuzufügen. 
Für weitere Informationen: [[Custom Samples]]

Um ein anderes Sample aus dem Ordner 'bd' abzuspielen, füge einen Doppelpunkt mit nachgestellter Nummer ein. 
Im folgenden Beispiel wird das vierte Bassdrum-Sample aus dem Ordner 'bd' abgespielt. 
(Es wird von Null hochgezählt, also rufst du mit ':3' das vierte Sample auf)

<source>
 d1 $ sound "bd:3"
</source>

Wenn du eine Zahl angibst, die größer als die Anzahl der Samples in einem Ordner ist, beginnt TidalCycles wieder von vorne zu zählen.. (Da die Nummerierung bei Null beginnt, wird in einem Ordner mit fünf Samples mit dem Code 'bd:5' das erste Sample gespielt, also 'bd:0')

Es ist auch möglich die Sample-Nummer separat anzugeben:

<source>
d1 $ sound "bd" # n "3"
</source>

Die Nützlichkeit dieser Vorgehensweise wird sich später zeigen.

==Sequenzen aus mehreren Samples==
Wenn du Anführungszeichen verwendest, kannst du eine Reihenfolge festlegen. Im Folgenden erhältst du beispielsweise ein Pattern aus Kick-Drum und Snare:

<source>
d1 $ sound "bd sd:1"
</source>

Wenn du diesen Code ausführst, ersetzt du das vorherige Pattern durch ein anderes und das im laufenden Betrieb. Herzlichen Glückwunsch, das ist LiveCoding.

==Mehr als eine Sequenz abspielen==
Der einfachste Weg, um mehrere Sequenzen gleichzeitig abzuspielen, ist die Verwendung von zwei oder mehr Verbindungen zum Synthesizer:


<source>
d1 $ sound "bd sd:1"

d2 $ sound "hh hh hh hh"


d3 $ sound "arpy"
</source>

ANMERKUNG: Jede Verbindung muss  separat in deinem Texteditor ausgeführt werden. Das heißt, du musst dreimal Strg+Eingabe drücken, einmal für jede Zeile. 
Achte darauf, dass zwischen den einzelnen Pattern eine Leerzeile eingefügt ist. Wenn sie direkt 
untereinander stehen,  wertet TidalCycles diese zusammen aus und das kann verwirrend werden. 
(Wenn du nur eine Zeile ausführen möchtest, kannst du Umschalt-Eingabe drücken).

Und wenn du Pattern lieber mit einem Namen anstelle einer Nummer referenzieren möchtest, geht das mit dem <source inline>p</source>, also zum Beispiel:

<source>
p "susan" $ sound "bd sd:1"

p "gerard" $ sound "hh hh hh hh"
</source>

==What is a Cycle?==
A cycle is the main “loop” of time in Tidal. The cycle repeats forever in the background, even when you’ve stopped samples from playing. The cycle’s duration always stays the same unless you modify it with setcps, we’ll cover this later. By default, there is one cycle per second.

Note that this omniprescent cyclic looping doesn’t necessary constrain you, for example it’s common to stretch a pattern outside of a single loop, and vary patterns from one loop to the next. We’ll see several ways to do this later, as well.

All of the samples inside of a pattern get squashed into a single cycle. The patterns below all loop over the same amount of time:

<source>
d1 $ sound "bd sd"

d1 $ sound "bd sd hh cp mt arpy drum"

d1 $ sound "bd sd hh cp mt arpy drum odx bd arpy bass2 feel future"
</source>

Note how the more steps you add to the pattern, the faster it plays them, in order to fit them all in. No matter how many samples you put in a pattern in this way, they will always be distributed evenly within a single cycle.

=Silence=
At this point you probably want to know how to stop the patterns you started. An empty pattern is defined as silence, so if you want to ‘switch off’ a pattern, you can just set it to that:

<source>
d1 silence
</source>

If you want to set all the connections (from d1 to d9) to be silent at once, there’s a single-word shortcut for that:

<source>
hush
</source>

You can also isolate a single connection and silence all others with the <source inline>solo</source> function. You can do this like so:

<source>
d1 $ sound "bd"

d2 $ sound "~ cp"

-- run this and only the bd plays
solo 1 

-- unsolo it and the cp plays again
unsolo 1 
</source>

=Patterns Within Patterns=

You can use Tidal’s square brackets syntax to create a pattern grouping:

<source>
d1 $ sound "[bd sd sd] cp"
</source>

Square brackets allow several events to be played inside of a single step. You can think of the above pattern as having two steps, with the first step broken down into a subpattern, which has three steps. Practically, this means you can create denser sub-divisions of cycles:

<source>
d1 $ sound "bd [sd sd]"

d1 $ sound "bd [sd sd sd]"

d1 $ sound "bd [sd sd sd sd]"

d1 $ sound "[bd bd] [sd sd sd sd]"

d1 $ sound "[bd bd bd] [sd sd]"

d1 $ sound "[bd bd bd bd] [sd]"
</source>

You can even nest groups inside groups to create increasingly dense and complex patterns:

<source>
d1 $ sound "[bd bd] [bd [sd [sd sd] sd] sd]"
</source>

A shorthand for this kind of grouping is to place a period . between groups, rather than surrounding them in square brackets. We call this technique ‘marking out feet’. For example these two patterns are equivalent:

<source>
d1 $ sound "bd bd . sd sd sd . bd sd"

d1 $ sound "[bd bd] [sd sd sd] [bd sd]"
</source>

The former approach is often easier to type, but is a relatively new addition to TidalCycles, and so many examples will use the square brackets.

==Layering (Polyrhythms) Instead of Grouping==
You can also layer up several loops, by using commas to separate the different parts:

<source>
d1 $ sound "[bd bd bd, sd cp sd cp]"
</source>

This would play the sequence bd bd bd at the same time as sd cp sd cp. Note that the first sequence only has three events, and the second one has four. Because tidal ensures both loops fit inside the same cyclic duration, you end up with a polyrhythm.

You can layer any number of these subpatterns to create many polyrhythms:

<source>
d1 $ sound "[bd bd bd, sd cp sd cp, arpy arpy, odx]"
</source>

And of course you can use groupings inside of the layers:

<source>
d1 $ sound "[bd bd bd, [sd sd] cp, arpy [arpy [arpy arpy] arpy arpy], odx]"
</source>

==Playing one step per cycle==
To specify a group where only one step is played per cycle, use angle brackets. For example:

<source>
d1 $ sound "bd <arpy:1 arpy:2 arpy:3>"
</source>

The above will result in the sequence <code>bd arpy:1 bd arpy:2 bd arpy:3</code>, over three cycles.

=Pattern Repetition and Speed=

==Repetition==
There are two short-hand symbols you can use inside patterns to speed things up or slow things down: * and /. You could think of these like multiplication and division.

Use the * symbol to make a pattern, or part of a pattern, repeat as many times as you’d like:

<source>
d1 $ sound "bd*2"
</source>

This is the same as doing <code>d1 $ sound "bd bd"</code>

The code above uses *2 to make a sample play twice.

You can use the / symbol to make a part of a pattern slow down, or occur less often:

<source>
d1 $ sound "bd/2"
</source>

The code above uses /2 to make a sample play half as often, or once every 2nd cycle.

Using different numbers works as you’d expect:

<source>
d1 $ sound "bd*3" -- plays the bd sample three times each cycle
d1 $ sound "bd/3" -- plays the bd samples only once each third cycle
</source>

==Using * and / on Groups==
You can apply the * and / symbols on groups of patterns:

<source>
d1 $ sound "[bd sn]*2 cp"

d1 $ sound "[bd sn] cp/2"

d1 $ sound "[[bd sn] cp]*2" -- speeds up the entire pattern by 2

d1 $ sound "[[bd sn] cp]/2" -- slows down the entire pattern by 2
</source>

You can also use the symbols on nested groups to create more complex rhythms:

<source>
d1 $ sound "[bd sn sn*3]/2 [bd sn*3 bd*4]/3"

d1 $ sound "[bd [sn sn]*2]/2 [bd [sn bd]/2]*2"
</source>

=Modifying Sequences With Functions=

Tidal comes into its own when you start building things up with functions which transform the patterns in various ways.

For example, <code>rev</code> reverses a pattern:

<source>
d1 $ rev (sound "bd*2 [bd [sn sn*2 sn] sn]")
</source>

That’s not so exciting, but things get more interesting when this is used in combination with another function. For example every takes three parameters: 
a number, a function and a pattern to apply the function to. The number specifies how often the function is applied to the pattern. For example, the 
following reverses the pattern every fourth repetition:

<source>
d1 $ every 4 (rev) (sound "bd*2 [bd [sn sn*2 sn] sn]")
</source>

It takes a while to get used to how we’re using parenthesis here. In the previous example, rev takes one parameter, a pattern, and we had to ‘wrap up’ the 
pattern sound <code>"[bd bd] [bd [sn [sn sn] sn] sn]"</code> in brackets to pass it to rev. In the above example every takes three parameters: a number, 
a function and a pattern. We had to wrap up the pattern as before, but also rev in order to give it to every. This should become clearer with practice.

You can also slow down or speed up the playback of a pattern, this makes it a quarter of the speed:

<source>
d1 $ slow 4 $ sound "bd*2 [bd [sn sn*2 sn] sn]"
</source>

And this four times the speed:

<source>
d1 $ fast 4 $ sound "bd*2 [bd [sn sn*2 sn] sn]"
</source>

Note that slow 0.25 would do exactly the same as fast 4.

Again, this can be applied selectively:

<source>
d1 $ every 4 (fast 4) $ sound "bd*2 [bd [sn sn*2 sn] sn]"
</source>

Note again the use of parenthesis, around fast 4. This is needed, to group together the function fast with its parameter 4, before being passed as a parameter to the function every.

In the examples above, the sound function takes a pattern of sample names, and turns it into a pattern of synthesizer triggers. 
This might take a while to fully understand, but the important thing to remember is that “it’s patterns all the way down”. 
In this case, this means that you can operate on the inner pattern of sample names, instead of the outer pattern of synthesizer triggers that sound gives you:

<source>
d1 $ sound (every 4 (fast 4) "bd*2 [bd [sn sn*2 sn] sn]")
</source>

The fast function is also known as density, which is actually the older name, so a lot of examples will use it instead of the 
(slightly quicker to type) fast. They do exactly the same thing.

==Where are all the functions?==
There are many types of functions that help you change patterns. Some of them re-order sequences, some alter time, some provide conditional logic, and some can help compose more complex patterns.

We’ll introduce many of the core functions in this introduction, and a more complete list of functions available in Tidal can be found on the [[Category:Functions|functions category]] page.

=Applying effects with control patterns=

TidalCycles has a number of effects that you can apply to sounds. Some of them do simple things like change volume, and others do more complex things like add delay or distortion. This is done with what we call ''control patterns''. In fact <source inline>sound</source> itself creates a control pattern, and we apply effects by combining control patterns together.

You can combine control patterns by adding the # operator between them:

<source>
d1 $ sound "bd*4" # crush "4"
</source>

The above code uses <source inline>crush</source> to create a bitcrushing control pattern with a value of 4 (which sounds really grungy), and uses <source inline>#</source> to join that with the <source inline>sound</source> control pattern.

You can combine multiple control patterns together, with the # operator:

<source>
d1 $ sound "bd*4" # crush "4" # speed "2"
</source>

The code above both bitcrushes and speeds up sample playback (which increases the ‘pitch’).

==Control values are patterns too==
You may notice that the values of effects are specified in double quotes. This means that you can pattern the effect values too:

<source>
d1 $ sound "bd*4" # gain "1 0.8 0.5 0.7"
</source>

The above <source inline>gain</source> effect changes how loud the sample is, good for patterns of emphasis as above. Other control patterns follow all the same grouping rules as sound patterns:

<source>
d1 $ sound "bd*4 sn*4" # gain "[[1 0.8]*2 [0.5 0.7]]/2"
</source>

And you can also apply functions to control patterns:

<source>
d1 $ sound "bd*4" # (every 3 (rev) $ gain "1 0.8 0.5 0.7")
</source>

Like with the sound example earlier, you must use parenthesis after gain in order to specify a function on the gain pattern.

This works too:

<source>
d1 $ sound "bd*4" # gain (every 3 (rev) $ "1 0.8 0.5 0.7")
</source>

In the above example, <source inline>every 3 (rev)</source> is being applied to <source inline>"1 0.8 0.5 0.7"</source>, which is a pattern of numbers. In the example preceding it, the same function was applied to <source inline>gain "1 0.8 0.5 0.7"</source>, which is a pattern of gain controls. In this case, whether you apply the function before or after the numbers are turned into controls doesn't matter too much, the outcome is exactly the same.

==Control pattern order==
You can specify the effect control ''before'' the sound control:

<source>
d1 $ gain "1 0.8 0.5 0.7" # sound "bd"
</source>

The order that you put things matters; with <source inline>#</source>the structure of the pattern is given by the pattern on the ''left''. In this case, only one bd sound is given, but you hear four, because the structure comes from the gain pattern on the left.

==Modifying control values==

The # operator is just a shortcut to a longer form of operator called <source inline>|></source>. The <source inline>|></source> operator is part of a family of operators, and means something special about combining patterns, which we’ll cover shortly. All you need to know right now is that <source inline>|></source> is used to combine patterns.

You can use <source inline>|></source> to combine patterns conditionally:

<source>
d1 $ every 2 (|> speed "2") $ sound "arpy*4" |> speed "1"
</source>

There are other types of operators that allow you to perform arithmetic:

 |+
 |-
 |*
 |/

For example, using <source inline>|+</source> will perform an addition operation and add to an original value:

<source>
d1 $ every 2 (|+ speed "1") $ sound "arpy*4" |> speed "1"
</source>

The code above results in a speed of “2” every other cycle.

The following will multiply values:

<source>
d1 $ every 2 (|* speed "1.5") $ sound "arpy*4" |> speed "1"
</source>

More complex patterns and chaining can be done, and with any effect, of course:

<source>
d1 $ every 3 (|- note "3") $ every 2 (|+ up "5") $ sound "arpy*4" |> note "0 2 4 5"
</source>

It might be worth sticking to just these ways of combining control patterns for now, but if you are curious, you can look into the [[Combining pattern structure|others that are available]].

==Some Common Effects==
Here is a quick list of some effects you can use in Tidal (the full list is available in the Reference section):

* gain - changes volume, values from 0 to 1
* pan - pans sound right and left, values from 0 to 1
* shape - a type of amplifier, values from 0 to 1
* vowel - a vowel formant filter, values include a, e, i, o, and u
* speed - changes playback speed of a sample, see below

=Shorthand for numerical patterns=

From version 0.9 of Tidal, there are some nice ways of saving on keypresses when working with numerical patterns.

For example, when specifying patterns of single numbers, such as:

<source>
d1 $ sound "arpy(3,8)" # n "2"
</source>

you can miss off the double quotes, so this works fine:

<source>
d1 $ sound "arpy(3,8)" # n 2
</source>

However, if you wanted more than one value in that n pattern, you’d have to put the quotes in:

<source>
d1 $ sound "arpy(3,8)" # n "2 5"
</source>

You can also treat patterns of numbers as simple numbers in other ways. For example doing algebra:

<source>
d1 $ sound "arpy(3,8)" # n ("0 2" * 2)

d1 $ sound "arpy(3,8)" # n (every 4 (* 2) "0 2")

d1 $ n (off 0.125 (+12) $ off 0.25 (+7) $ slow 2 $ "0(3,8) [5 7]") # sound "supergong"
</source>

(The <source inline>supergong</source> sound requires <source inline>sc3-plugins</source> to be installed.)

This is still quite new to everyone, so you will not see it used much in the documentation yet.

You can also now specify increasing or decreasing numbers with a range, for example this:

<source>
 d1 $ n "[0 .. 7] [3 .. 1]" # sound "supergong"
</source>

... is shorthand for:

<source>
d1 $ n "[0 1 2 3 4 5 6 7] [3 2 1]" # sound "supergong"
</source>

=Sample Playback Speed (and Pitch)=

You can change the playback speed of a sample in TidalCycles by using the speed effect. You can use speed to change pitches, to create a weird effect, or to match the length of a sample to a specific period of the cycle time (but see the loopAt function for an easy way of doing the latter).

You can set a sample’s speed by using the speed effect with a number.

* speed "1" plays a sample at its original speed
* speed "0.5" plays a sample at half of its original speed
* speed "2" plays a sample at double its original speed

 <source>d1 $ sound "arpy" # speed "1"

d1 $ sound "arpy" # speed "0.5"

d1 $ sound "arpy" # speed "2"</source>

Just like other effects, you can specify a pattern for speed:

 d1 $ speed "1 0.5 2 1.5" # sound "arpy" 

You can also reverse a sample by specifying negative values:

<source>
d1 $ speed "-1 -0.5 -2 -1.5" # sound "arpy"
</source>

==Play a sample at multiple speeds simultaneously==
Use the pattern grouping syntax with a comma to cause speed to play a sample back at multiple speeds at the same time:

<source>
d1 $ sound "arpy" # speed "[1, 1.5]"
d1 $ speed "[1 0.5, 1.5 2 3 4]" # sound "arpy"
</source>

==12-tone scale speeds==
You can also use the up function to change playback speed. up is a shortcut effect that matches speeds to half steps on a 12-tone scale. For example, the following plays a chromatic scale:

<source>
d1 $ up "0 1 2 3 4 5 6 7 8 9 10 11" # sound "arpy"
</source>

You can also use the run function to create an incrementing pattern of integers: 

<source>
d1 $ up (run 12) # sound "arpy". 
</source>

The <code>run</code> function will be discussed later.

=Euclidean Sequences=
If you give two numbers in parenthesis after an element in a pattern, then Tidal will distribute the first number of sounds equally across the second number of steps:

<source>
d1 $ sound "bd(5,8)"
</source>

You can also use the [[euclid]] function to do this. [[euclid]] takes the same two arguments as what is used in the parenthesis above:

<source>
d1 $ euclid 5 8 $ sound "bd"
</source>

You can use the parenthesis notation within a single element of a pattern:

<source>
d1 $ sound "bd(3,8) sn*2"
</source>

<source>
d1 $ sound "bd(3,8) sn(5,8)"
</source>

You can also add a third parameter, which ‘rotates’ the pattern so it starts on a different step:

<source>
d1 $ sound "bd(5,8,2)"
</source>

You can also use the euclid function to apply a Euclidean algorithm over a complex pattern, although the structure of that pattern will be lost:

<source>
d1 $ euclid 3 8 $ sound "bd*2 [sn cp]"
</source>

In the above, three sounds are picked from the pattern on the right according to the structure given by the euclid 3 8. It ends up picking two bd sounds, a cp and missing the sn entirely.

As a bonus, it is possible to pattern the parameters within the parenthesis, for example to alternate between 3 and 5 elements:

<source>
d1 $ sound "bd([5 3]/2,8)"
</source>

These types of sequences use “Bjorklund’s algorithm”, which wasn’t made for music but for an application in nuclear physics, which is exciting. More exciting still is that it is very similar in structure to the one of the first known algorithms written in Euclid’s book of elements in 300 BC. You can read more about this in the paper The Euclidean Algorithm Generates Traditional Musical Rhythms by Toussaint. Some examples from this paper are included below, including rotation in some cases.

* (2,5) : A thirteenth century Persian rhythm called Khafif-e-ramal.
* (3,4) : The archetypal pattern of the Cumbia from Colombia, as well as a Calypso rhythm from Trinidad.
* (3,5,2) : Another thirteenth century Persian rhythm by the name of Khafif-e-ramal, as well as a Rumanian folk-dance rhythm.
* (3,7) : A Ruchenitza rhythm used in a Bulgarian folk-dance.
* (3,8) : The Cuban tresillo pattern.
* (4,7) : Another Ruchenitza Bulgarian folk-dance rhythm.
* (4,9) : The Aksak rhythm of Turkey.
* (4,11) : The metric pattern used by Frank Zappa in his piece titled Outside Now.
* (5,6) : Yields the York-Samai pattern, a popular Arab rhythm.
* (5,7) : The Nawakhat pattern, another popular Arab rhythm.
* (5,8) : The Cuban cinquillo pattern.
* (5,9) : A popular Arab rhythm called Agsag-Samai.
* (5,11) : The metric pattern used by Moussorgsky in Pictures at an Exhibition.
* (5,12) : The Venda clapping pattern of a South African children’s song.
* (5,16) : The Bossa-Nova rhythm necklace of Brazil.
* (7,8) : A typical rhythm played on the Bendir (frame drum).
* (7,12) : A common West African bell pattern.
* (7,16,14) : A Samba rhythm necklace from Brazil.
* (9,16) : A rhythm necklace used in the Central African Republic.
* (11,24,14) : A rhythm necklace of the Aka Pygmies of Central Africa.
* (13,24,5) : Another rhythm necklace of the Aka Pygmies of the upper Sangha.

=Tempo=

If you’ve made it this far without changing the tempo in all these examples, then you’re probably ready to change it up.

Tidal’s core unit of time is cycles per second. It can be set with the <source inline>setcps</source> function:

<source>
setcps 1
</source>

You can execute setcps just like a pattern (using Shift+Enter in your editor).

<source inline>setcps</source> accepts a positive numeric value that can include a decimal:

<source>
setcps 1.5
setcps 0.75
setcps 10
</source>

Tidal’s timing is based on cycles, rather than beats, however it is more common for people to think in terms of beats per minute (BPM). If you prefer to think in this way, you have to decide how many beats you want to have per cycle, and divide accordingly. For example if you wanted to play at 140 bpm, with four beats per cycle, then you could do:

<source>
setcps (140/60/4)
</source>

You can also pattern the tempo with the <source inline>cps</source> control function, for example:

<source>
d1 $ sound "cp(3,8)"
  # cps (slow 8 $ range 0.8 1.6 saw)
</source>

=The Run Function=

There is a special utility function called run which will return a pattern of integers up to a specified maximum. You can use run with effects to aid in automatically generating a linear pattern:

<source>
d1 $ sound "arpy*8" # up (run 8)
d1 $ sound "arpy*8" # speed (run 8)
</source>

In the above we’re specifying the number of sounds twice - in the sound pattern as well as the up or speed pattern. There’s actually a neat way of only having to specify this once, simply by switching them round, so the effect parameter is on the left:

<source>
d1 $ up (run 8) # sound "arpy"
</source>

This works because TidalCycles always takes the structure of a pattern from the parameter that’s on the left. We usually want the structure to come from the sound parameter, but not always.

Because run returns a pattern, you can apply functions to its result:

<source>
d1 $ sound "arpy*8" # up (every 2 (rev) $ run 8)
</source>

For a more practical example of using run, read below about selecting samples from folders.

=(Algorithmically) Selecting Samples=

The sound parameter we’ve been using up to now can actually be broken into two separate parameters, making it easy to select samples with a pattern. These parameters are s that gives the name of the sample set, and n which gives the number of the sample within that set. For example, the following two patterns do exactly the same:

<source>
d1 $ sound "arpy:0 arpy:2 arpy:3"
d1 $ n "0 2 3" # s "arpy"
</source>

It’s possible to break the sound parameter into two different patterns, namely s that gives the name of the sample set, and n which gives the index of the sample within that set. For example, the following two patterns are the same:

<source>
d1 $ sound "arpy:0 arpy:2 arpy:3"
d1 $ n "0 2 3" # s "arpy"
</source>

This allows us to separate the sample folder name from the index inside the folder, possibly with surprising results!

There is also special function called samples that lets you do the same using the sound parameter.

<source>
d1 $ sound $ samples "drum*4" "0 1 2 3"
</source>

the code above is the same as this:

<source>
d1 $ sound "drum:0 drum:1 drum:2 drum:3"
</source>

Whether you use n and s together, or sound with samples is up to you, although you might find the former to be more flexible.

Remember the run function? Since run generates a pattern of integers, it can be used with n to automatically “run” through the sample indices of a folder:

<source>
d1 $ n (run 4) # s "drum"
d1 $ sound $ samples "drum*4" (run 4) -- or with samples
</source>

And of course you can specify a different pattern of sample names:

<source>
d1 $ s "drum arpy cp hh" # n (run 10)
</source>

Again, by swapping the order of the s and n parameters, you can hear the difference between taking the structure from one or the other:

<source>
d1 $ n (run 10) # s "drum arpy cp hh"
</source>

NOTE: if you specify a run value that is greater than the number of samples in a folder, then the higher number index will “wrap” to the beginning of the samples in the folder (just like with the colon notation).

You might sometimes see the samples function wrapped in parenthesis:

<source>
d1 $ sound (samples "drum arpy cp hh" (run 10))
</source>

=Combining Types of Patterns=

Ok, remember when we started adding effects:

<source>
d1 $ sound "bd sn drum arpy" # pan "0 1 0.25 0.75"
</source>

What we’re actually doing in the code above is combining two patterns together: the sound pattern, and the pan pattern. The special pipe operators (|>, |+, |-, |*, |/, |>, and so on), allow us to combine two patterns. Remember that # is shorthand for |>.

We can actually swap sides and it sounds the same:

<source>
d1 $ pan "0 1 0.25 0.75" # sound "bd sn drum arpy"
</source>

As we touched on earlier, the main thing to know when combining patterns like this is that the left-most pattern determines the rhythmic structure of the result. Removing one of the elements from the pan pattern on the left results in a cycle with three samples played:

<source>
d1 $ pan "0 1 0.25" # sound "bd sn drum arpy"
</source>

In the code above, the pan pattern determines the rhythm because it is the left-most pattern. The sound pattern now only determines what samples are played at what time. The sound pattern gets mapped onto the pan pattern.

You might be wondering how TidalCycles decides which sound values get matched with which pan values in the above. (If not, there is no need to read the rest of this paragraph just now!) The rule is, for each value in the pattern on the left, values from the right are matched where the start (or onset) of the left value, fall within the timespan of the value on the right. For example, the second pan value of 1 starts one third into its pattern, and the second sound value of sn starts one quarter into its pattern, and ends at the halfway point. Because the former onset (one third) falls inside the timespan of the latter timespan (from one quarter until one half), they are matched. The timespan of arpy doesn’t contain any onsets from the pan pattern, and so it doesn’t match with anything, and isn’t played.

The rule described above may seem like a lot to keep in mind while composing patterns, but in practice there is no need. Our advice is to not worry, write some patterns and get a feel for how they fit together.

Anyway, this composition of pattern parameters allows us to do some unique things:

<source>
d1 $ up "0 0*2 0*4 1" # sound "[arpy, bass2, bd]"
</source>

Above, the sound pattern is merely specifying three samples to play on every note. Both the rhythm and pitch of these notes is defined by the up pattern.

It's also possible to switch things around so that structure comes from the right, by using the operators >|, *|, +|, /| and -|, instead of |>, |*, |+ and |-, for example:

<source>
d1 $ sound "drum" >|  n "0 1*2 ~ 3"
</source>

The side of the operator that the | is on, is where the structure comes from. In fact, if you put the bar on both sides, structure comes from both sides:

<source>
d1 $ sound "drum cp" >|  n "0 1 2"
</source>

=Oscillation with Continuous Patterns=

So far we’ve only been working with discrete patterns, by which we mean patterns which containing events which begin and end. Tidal also supports continuous patterns which instead vary continually over time. You can create continuous patterns using functions which give sine, saw, triangle, and square waves:

<source>
d1 $ sound "bd*16" # pan sine
</source>

The code above uses the sine pattern to specify a sine wave oscillation of values between 0 and 1 for the pan values, so the bass drum moves smoothly between the left and right speakers.

Tidal used to have sine and sine1 patterns with different ranges, but now they are aliases, with both giving a range from 0 to 1.

In addition to the sine pattern, Tidal also has saw, tri, and square, for sawtooth, triangle and square waves respectively.

Just like discrete patterns, you can control the speed of continuous patterns with slow or density:

<source>
d1 $ sound "bd*16" # pan (slow 8 $ saw)
d1 $ sound "bd*8 sn*8" # pan (density 1.75 $ tri)
d1 $ sound "bd*8 sn*8" # speed (density 2 $ tri)
</source>

You can also combine them in different ways:

<source>
d1 $ sound "bd*16" # pan (slowcat [sine, saw, square, tri])
d1 $ sound "sn:2*16" # speed ((range 0.5 3 sine) * (slow 4 saw))
</source>

==Scaling Oscillation==
You can tell the oscillation functions to scale themselves and oscillate between two values using range:

A recent change in tidal repurposed the old scale function to range, to free scale to be used for other purposes.

<source>
d1 $ sound "bd*8 sn*8" # speed (range 1 3 $ tri)
d1 $ sound "bd*8 sn*8" # speed (slow 4 $ range 1 3 $ tri)
</source>

You can also scale to negative values, but make sure to wrap negative values in parens (otherwise the interpreter thinks you’re trying to subtract 2 from something):

<source>
d1 $ sound "bd*8 sn*8" # speed (range (-2) 3 $ tri)
</source>

This technique works well for a slow low-pass filter cutoff:

<source>
d1 $ sound "hh*32" # cutoff (range 300 1000 $ slow 4 $ sine) # resonance "0.4"
</source>

'''NOTE''': Despite the fact that these oscillator patterns produce continuous values, you still need to combine them with discrete sound patterns.

=Rests=

So far we have produced patterns that keep producing more and more sound. What if you want a rest, or gap of silence, in your pattern? You can use the “tilde” ~ character to do so:

<source>
d1 $ sound "bd bd ~ bd"
</source>

Think of the <code>~</code> as an ‘empty’ step in a sequence, that just produces silence.

=Polymeters=

We talked about polyrhythms earlier, but Tidal can also produce polymeter sequences. A polymeter pattern is one where two patterns have different sequence lengths, but share the same pulse or tempo.

You use curly brace syntax to create a polymeter rhythm:

<source>
d1 $ sound "{bd hh sn cp, arpy bass2 drum notes can}"
</source>

The code above results in a five-note rhythm being played at the pulse of a four-note rhythm. If you switch the groups around, it results in a four-note rhythm over a five-note rhythm:

<source>
d1 $ sound "{arpy bass2 drum notes can, bd hh sn cp}"
</source>

Sometimes you might want to create an odd polymeter rhythm without having to explicitly create a base rhythm. You could do this with rests:

<source>
d1 $ sound "{~ ~ ~ ~, arpy bass2 drum notes can}"
</source>

But a more efficient way is to use the % symbol after the closing curly brace to specify the number of notes in the base pulse:

<source>
d1 $ sound "{arpy bass2 drum notes can}%4"
</source>

the above is the same as this:

<source>
d1 $ sound "{~ ~ ~ ~, arpy bass2 drum notes can}"
</source>

If “polymeter” sounds a bit confusing, there’s a good explanation here: http://music.stackexchange.com/questions/10488/polymeter-vs-polyrhythm

=Shifting Time=

You can use the <code>~></code> and <code><~</code> functions to shift patterns forwards or backwards in time, respectively. With each of these functions, you can specify an amount, in cycle units.

<source>
d1 $ (0.25 <~) $ sound "bd*2 cp*2 hh sn"
d1 $ (0.25 ~>) $ sound "bd*2 cp*2 hh sn"
</source>

The above code shifts the patterns over by one quarter of a cycle.

You can hear this shifting effect best when applying it conditionally. For example, the below shifts the pattern every third cycle:

<source>
d1 $ every 3 (0.25 <~) $ sound "bd*2 cp*2 hh sn"
d1 $ every 3 (0.25 ~>) $ sound "bd*2 cp*2 hh sn"
</source>

You can shift patterns as little or as much as you’d like:

<source>
d1 $ every 3 (0.0625 <~) $ sound "bd*2 cp*2 hh sn"
d1 $ every 3 (1000 ~>) $ sound "bd*2 cp*2 hh sn"
d1 $ every 3 (1000.125 ~>) $ sound "bd*2 cp*2 hh sn"
</source>

However, in the above case every cycle is the same, so you won’t here a difference between shifting it 1 or 1000 cycles.

You can also specify a pattern for the shift amount:

<source>
d1 $ "[0 0.25]/4" <~ (sound "bd*2 cp*2 hh sn")
</source>

=Introducing Randomness=

Tidal can produce random patterns of integers and decimals. It can also introduce randomness into patterns by removing random events.

==Random Decimal Patterns==
You can use the rand function to create a random value between 0 and 1. This is useful for effects:

<source>
d1 $ sound "arpy*4" # pan (rand)
</source>

As with run and all numeric patterns, the values that rand give you can be scaled, for example the below gives random numbers between 0.25 and 0.75:

<source>
d1 $ sound "arpy*4" # pan (range 0.25 0.75 $ rand)
</source>

==Random Integer Patterns==
Use the irand function to create a random integer up to a given maximum. The most common usage of irand is to produce a random pattern of sample indices (similar to run):

<source>
d1 $ s "arpy*8" # n (irand 30)
</source>

The code above randomly chooses from 30 samples in the “arpy” folder.

Hairy detail: rand and irand are actually continuous patterns, which in practical terms means they have infinite detail - you can treat them as pure information! As with all patterns they are also deterministic, stateless functions of time, so that if you retriggered a pattern from the same logical time point, exactly the same numbers would be produced. Furthermore, if you use a rand or irand in two different places, you would get the same ‘random’ pattern - if this isn’t what you want, you can simply shift or slow down time a little for one of them, e.g. slow 0.3 rand.

==Removing or “Degrading” Pattern events==
Tidal has a few ways to randomly remove events from patterns. You can use the shorthand ? symbol if you want to give an event a 50/50 chance of happening or not on every cycle:

<source>
d1 $ sound "bd? sd? sd? sd?"
</source>

In the code above, the whole sample has a 50% chance if it will be played or if the whole cycle will be silent.

You can add the ? after the completion of any event or group in a pattern:

<source>
d1 $ sound "bd*16?"
d1 $ sound "bd sn? cp hh?"
d1 $ sound "[bd sn cp hh]?"
</source>

The <code>?</code> symbol is shorthand for the degrade function. The two lines below are equivalent:

<source>
d1 $ sound "bd*16?"
d1 $ degrade $ sound "bd*16"
</source>

Related to degrade is the degradeBy function, where you can specify the probability (from 0 to 1) that events will be removed from a pattern:

<source>
d1 $ degradeBy 0.25 $ sound "bd*16"
</source>

There is also sometimesBy, which executes a function based on a probability:

<source>
d1 $ sometimesBy 0.75 (# crush 4) $ sound "bd arpy sn ~"
</source>

The code above has a 75% chance of applying the bitcrush effect pattern # crush 4 on every event in the sound pattern.

There are other aliases for sometimesBy:

<source>
sometimes = sometimesBy 0.5
often = sometimesBy 0.75
rarely = sometimesBy 0.25
almostNever = sometimesBy 0.1
almostAlways = sometimesBy 0.9
</source>

e.g.:

<source>
d1 $ rarely (# crush 4) $ sound "bd*8"
</source>

=Creating Variation in Patterns=

You can create a lot of cyclic variations in patterns by layering conditional logic:

<source>
d1 $ every 5 (|+| speed "0.5") $ every 4 (0.25 <~) $ every 3 (rev) $
  sound "bd sn arpy*2 cp"
  # speed "[1 1.25 0.75 -1.5]/3"
</source>

In addition to every you can also use the whenmod conditional function. whenmod takes two parameters; it executes a function 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 will play a pattern normally for cycles 1-6, then play it in reverse for cycles 7-8. Then normally again for six cycles, then in reverse for two, and so on:

<source>
d1 $ whenmod 8 6 (rev) $ sound "bd*2 arpy*2 cp hh*4"
</source>

=Creating "Fills" and using "const"=

You can think of a “fill” as a change to a regular pattern that happens regularly. e.g. every 4 cycles do “xya”, or every 8 cycles do “abc”.

We’ve already been using every and whenmod to do pattern function fills:

<source>
d1 $ every 8 (rev) $ every 4 (density 2) $ sound "bd hh sn cp"
d1 $ whenmod 16 14 (# speed "2") $ sound "bd arpy*2 cp bass2"
</source>

However, what if you wanted to conditionally replace the pattern with a new one? You can use the const function to completely replace a playing pattern.

Let’s start with a trivial example where we use const to replace an entire pattern all the time:

<source>
d1 $ const (sound "arpy*3") $ sound "bd sn cp hh"
</source>

In the code above, we’ve completely replaced the “bd sn cp hh” pattern with an “arpy” pattern. const specifies the new pattern.

We can conditionally apply const using every or whenmod:

<source>
d1 $ whenmod 8 6 (const $ sound "arpy(3,8) bd*4") $ sound "bd sn bass2 sn"
d1 $ every 12 (const $ sound "bd*4 sn*2") $ sound "bd sn bass2 sn"
</source>

=Composing Multi-Part Patterns=

There are a few ways that you can compose new patterns from multiple other patterns. You can concatenate or “append” patterns in serial, or you can “stack” them and play them together in parallel.

==Concatenating patterns in serial==
You can use the <code>fastcat</code> function to add patterns one after another:

<source>
d1 $ fastcat [sound "bd sn:2" # vowel "[a o]/2",
             sound "casio casio:1 casio:2*2"
            ]
</source>

The <code>fastcat</code> function squeezes all the patterns into the space of one. The more patterns you add to the list, the faster each pattern will be played so that all patterns can fit into a single cycle.

<source>
d1 $ fastcat [sound "bd sn:2" # vowel "[a o]/2",
             sound "casio casio:1 casio:2*2",
             sound "drum drum:2 drum:3 drum:4*2"
            ]
</source>

<code>cat</code> (also known as <code>slowcat</code>), will maintain the original playback speed of the patterns:

<source>
d1 $ cat [sound "bd sn:2" # vowel "[a o]/2",
         sound "casio casio:1 casio:2*2",
         sound "drum drum:2 drum:3 drum:4*2"
        ]
</source>

<code>cat</code> is a great way to create a linear sequence of patterns (a sequence of sequences), giving a larger form to multiple patterns.

There’s also <code>randcat</code>, which will play a random pattern from the list.

==Playing patterns together in parallel==

The <code>stack</code> function takes a list of patterns and combines them into a new pattern by playing all of the patterns in the list simultaneously.

<source>
d1 $ stack [
 sound "bd bd*2",
 sound "hh*2 [sn cp] cp future*4",
 sound (samples "arpy*8" (run 16))
]
</source>

This is useful if you want to apply functions or effects on the entire stack:

<source>
d1 $ every 4 (slow 2) $ whenmod 5 3 (# speed "0.75 1.5") $ stack [
 sound "bd bd*2",
 sound "hh*2 [sn cp] cp future*4",
 sound (samples "arpy*8" (run 16))
] # speed "[[1 0.8], [1.5 2]*2]/3"
</source>

=Truncating samples with "cut"=

So far, all of our examples have used short samples. However, maybe you’ve experimented with some long samples. Maybe you’ve noticed that really long samples can cause a lot of bleed and unwanted sound.

With Tidal’s cut effect, you can “choke” a sound and stop it from playing when a new sample is triggered.

Consider the following example where we have a pattern of “arpy” sounds, played at a low speed, so there is a lot of bleed into each sample:

<source>
d1 $ sound (samples "arpy*8" (run 8)) # speed "0.25"
</source>

We can stop this bleed by using cut and assigning the pattern a cut group of “1”:

<source>
d1 $ sound (samples "arpy*8" (run 8)) # speed "0.25" # cut "1"
</source>

No more bleed!

You can use any number for the cut group.

Cut groups are global, to the Tidal process, so if you have two Dirt connections, use two different cut group values to make sure the patterns don’t choke each other:

<source>
d1 $ sound (samples "arpy*8" (run 8)) # speed "0.25" # cut "1"
d2 $ sound (samples "bass2*6" (run 6)) # speed "0.5" # cut "2"
</source>

This also works in a stack:

<source>
d1 $ stack [
  sound (samples "arpy*8" (run 8)) # speed "0.25" # cut "1",
  sound (samples "bass2*6" (run 6)) # speed "0.5" # cut "2" ]
</source>

=Transitions Between Patterns=

Changing the pattern on a channel takes effect (almost) immediately. This may not be what you want, especially when performing live!

That’s why Tidal allows you to choose a transition that will introduce another pattern, eventually replacing the current one.

So once we have something running on d1, we can use the same channel number (1), passed to a nice transition function:

<source>
d1 $ sound (samples "hc*8" (iter 4 $ run 4))
</source>

<source>
anticipate 1 $ sound (samples "bd(3,8)" (run 3))
</source>

To transition from here, simply change the pattern, and in this case also change the transition function:

<source>
xfadeIn 1 16 $ sound "bd(5,8)"
</source>

The above will fade over 16 cycles from the former pattern to the given new one.

Apart from <code>anticipate</code> and <code>xfadeIn</code> there are a lot more transition functions 
e.g. some that will force you to keep changing your patterns to avoid repetitive performances.

=Samples=

If you’re using SuperDirt, all the default samples can be found in the Dirt-Samples folder - you can open it by running Quarks.gui in SuperCollider, 
clicking on “Dirt-Samples” and then “open folder”. If you’re using classic dirt, look in its samples subfolder. Here’s some you could try:

 <nowiki>flick sid can metal future gabba sn mouth co gretsch mt arp h cp
cr newnotes bass crow hc tabla bass0 hh bass1 bass2 oc bass3 ho
odx diphone2 house off ht tink perc bd industrial pluck trump
printshort jazz voodoo birds3 procshort blip drum jvbass psr
wobble drumtraks koy rave bottle kurt latibro rm sax lighter lt
arpy feel less stab ul</nowiki>

Each one is a folder containing one or more wav files. For example when you put bd:1 in a sequence, you’re picking up the second wav file in the bd folder. If you ask for the ninth sample and there are only seven in the folder, it’ll wrap around and play the second one.

If you want to add your own samples, just create a new folder in the samples folder, and put wav files in it.

=Synths=

For this section to work, you need to have installed the SuperCollider sc3-plugins. You can either install the latest version from git, or if you are using Linux, you may find it in your package manager. On Fedora the package is called supercollider-sc3-plugins.

SuperDirt is created with SuperCollider, a fantastic synthesis engine and language with huge sonic possibilities. You can trigger custom SuperCollider synths from TidalCycles in much the same way as you trigger samples. For example:

<source>
d1 $ midinote "60 62*2" # s "supersaw"
</source>

The above plays note 60 and 62 of the MIDI scale, using the midinote parameter. You can alternatively specify notes by name, using n:

<source>
d1 $ n "c5 d5*2" # s "supersaw"
</source>

For half tones you add the suffixes “f” or “s” (flat or sharp) to the note in question.

<source>
d1 $ n "<[a5,cs5,e5,g5]*3 [d5,fs5,g5,c5]>" # s "supersquare" # gain "0.7"
</source>

Above is a two chord progression A7 D7. Notice cs5 and fs5 as C#5 and F#5, respectively.

<source>
d2 $ every 4 (rev) $ n "<[g5 df5 e5 a5] [gf5 d5 c5 g5]*3>" # s "supersaw"
</source>

Now the same chords (A7 D7) this time played as ascending and descending arpeggios and cs5 written as df5and fs5 as gf5. Play both examples together for more fun!

You can also specify note numbers with n, but where 0 is middle c (rather than 60 with midinote).

<source>
d1 $ n "0 5" # s "supersaw"
</source>

The default sustain length is a bit long so the sounds will overlap, you can adjust this using the sustain parameter

<source>
d1 $ n "c5 d5*2" # s "supersaw" # sustain "0.4 0.2"
</source>

Many example synths can be found in the default-synths-extra.scd file in the SuperDirt/library folder or in default-synths.scd and tutorial-synths.scd in the SuperDirt/synths folder. These include:

* a series of tutorials: tutorial1, tutorial2, tutorial3, tutorial4, tutorial5
* examples of modulating with the cursor or sound input: pmsin, in, inr
* physical modeling synths: supermandolin, supergong, superpiano, superhex
* a basic synth drumkit: superkick, superhat, supersnare, superclap, super808
* four analogue-style synths: supersquare, supersaw, superpwm, supercomparator
* two digital-style synths: superchip, supernoise

To find the SuperDirt folder, simply run Quarks.folder in supercollider. The full folder location should appear in the postwindow (which is usually in the bottom right).

Many of the above synths accept additional Tidal Parameters or interpret the usual parameters in a slightly different way. For complete documentation, see default-synths.scd, but here are some examples to try:

<source>
d1 $ jux (# accelerate "-0.1") $ s "supermandolin*8" # midinote "[80!6 78]/8"
 # sustain "1 0.25 2 1"
</source>

<source>
d1 $ midinote (slow 2 $ (run 8) * 7 + 50) # s "supergong" # decay "[1 0.2]/4"
 # voice "[0.5 0]/8" # sustain (slow 16 $ range 5 0.5 $ saw1)
</source>

<source>
d1 $ sound "superhat:0*8" # sustain "0.125!6 1.2" # accelerate "[0.5 -0.5]/4"
</source>

<source>
d1 $ s "super808 supersnare" # n (irand 5)
 # voice "0.2" # decay "[2 0.5]/4" # accelerate "-0.1" # sustain "0.5" # speed "[0.5 2]/4"
</source>

<source>
d1 $ n (slow 8 "[[c5 e5 g5 c6]*4 [b4 e5 g5 b5]*4]") # s "superpiano"
 # velocity "[1.20 0.9 0.8 1]"
</source>

<source>
d1 $ n (slow 8 $ "[[c4,e4,g4,c5]*4 [e4,g4,b5,e5]*4]" + "<12 7>") # s "superpiano"
 # velocity (slow 8 $ range 0.8 1.1 sine) # sustain "8"
</source>

<source>
d1 $ n "[c2 e3 g4 c5 c4 c3]/3" # s "[superpwm supersaw supersquare]/24" # sustain "0.5"
 # voice "0.9" # semitone "7.9" # resonance "0.3" # lfo "3" # pitch1 "0.5" # speed "0.25 1"
</source>

<source>
d1 $ every 16 (density 24 . (|+| midinote "24") . (# sustain "0.3") . (# attack "0.05"))
 $ s "supercomparator/4" # midinote ((irand 24) + 24)
 # sustain "8" # attack "0.5" # hold "4" # release "4"
 # voice "0.5" # resonance "0.9" # lfo "1" # speed "30" # pitch1 "4"
</source>

<source>
d1 $ n "[c2 e3 g4 c5 c4 c3]*4/3" # s "superchip" # sustain "0.1"
 # pitch2 "[1.2 1.5 2 3]" # pitch3 "[1.44 2.25 4 9]"
 # voice (slow 4 "0 0.25 0.5 0.75") # slide "[0 0.1]/8" # speed "-4"
</source>

<source>
d2 $ every 4 (echo (negate 3/32)) $ n "c5*4" # s "supernoise"
 # accelerate "-2" # speed "1" # sustain "0.1 ! ! 1" # voice "0.0"
</source>

<source>
d1 $ s "supernoise/8" # midinote ((irand 10) + 30) # sustain "8"
 # accelerate "0.5" # voice "0.5" # pitch1 "0.15" # slide "-0.5" # resonance "0.7"
 # attack "1" # release "20" # room "0.9" # size "0.9" # orbit "1"
</source>

This is all quite new and under ongoing development, but you can read about modifying and adding your own synths to SuperDirt at its github repository.