Patterns: writing rhythm as a function of time

pat("bd sd hh hh") is a pattern, and a pattern is a function you can ask what is sounding between here and there. Ask it about one cycle and you get four events. Ask about the second half and you get two. Ask about a hundred cycles and it will tell you, because nothing was ever stored; the events are computed from the query.

This is why patterns compose. A pattern can be reversed, slowed, sliced, stacked against another, or handed a continuous curve to read its volume from, and none of those operations has to know how long the music is or where it will be sampled. The design comes from TidalCycles, and where Field's operators share a name with Tidal's they mean the same thing; the places they do not are listed below.

The piano rolls on this page show the events each pattern produces, and the clips under the mini-notation forms play those events through the Tidal drum samples (Dirt-Samples). Sound shows how to play a pattern through them from a box.

Two things every pattern is made of

An event is a value with a span of time. A query is a span you ask about. The whole language is functions from queries to lists of events.

// Nothing is stored. Ask the same pattern three different questions.
val drums = pat("bd sd hh hh")

val answers = [
    "one cycle" to PatArc(PatQ.ZERO, PatQ.ONE),
    "second half" to PatArc(PatQ.of(1, 2), PatQ.ONE),
    "cycle 97" to PatArc(PatQ.of(97), PatQ.of(98)),
].joinToString("\n") { (label, arc) ->
    "%-12s %s".format(label, drums.events(arc).joinToString("  ") { "${it.value}@${it.arc.start}" })
}
println(answers)
display("<pre>" + answers + "</pre>")

Time is exact rational arithmetic (PatQ), never floating point. A sixteenth note is 1/16, not 0.0625, so a pattern subdivided into thirds and one subdivided into fifths still line up perfectly fifteen cycles later.

Mini-notation

The string inside pat(...) is a small language of its own, and it is the same mini-notation TidalCycles uses. A space divides, brackets group, and about a dozen suffixes say the things a space cannot. Each form gets a card below: the notation, a piano roll of exactly what it schedules, and a clip of it.

Colour is the instrument (bd blue, sd orange, cp pink, oh green, hh yellow), so two bars that look different sound different. Height is pitch, so the kick sits at the bottom of every lane and the hats at the top, here and in every roll further down the page. Each rectangle is one event of the pattern.

Steps, and the space between them

A space is the only separator the notation has, and it always means divide this level evenly. Everything below is a way of saying something other than "evenly".

Two ways to group

Brackets are not the only way to carve up a cycle. One of these avoids the brackets and the other ignores the cycle's division entirely.

Speed, repetition, and width

Four postfix modifiers, and two markers that spell two of them without the punctuation. Every one of them attaches to the step on its left, including a bracketed group.

Forms that make the next cycle different

Up to here the notation has described a single bar that then repeats. These four are the point at which it stops doing that, and they are the reason a pattern is a function of time rather than a list of notes. Each is drawn over four cycles.

Polymeter

Braces divide by a step count rather than by the cycle, which is the one thing brackets and commas cannot express.

Rhythms the notation generates for you

Two bracket suffixes that do not spell a rhythm out but construct one, from a step count and a rule.

A value on a step

The last suffix is not about time at all.

Every card above is one line in a box, and the same renderer draws whatever you are editing:

showPatMini("polymeter-sub") // the published card
showPatRollOf("mine" to pat("bd(5,8,2), hh*8?0.2"), cycles = 4) // anything else, same scale
showPatAudio(pat("bd(5,8,2), hh*8?0.2"), cycles = 4, cps = 2.0) // and hear it

Continuous signals

sine(), saw(), tri(), square(), perlin() and rand() are patterns too. They just answer every query with exactly one event, sampled at the query's exact midpoint. They have no rhythm of their own, so you either give them one with segment(n) or hand them to something that already has one.

:::static
// Six signals through segment(16), two cycles. The polyline is the value each cell
// latched; the rectangle height is the same number.
showPatRoll("signals-segment")
:::fold open the output pane
displayOpen("main")
:::endfold

The midpoint convention is what makes the picture readable: sine() peaks a quarter of the way in, square() switches exactly on the half, saw() climbs monotonically.

A parameter can be a function

The useful consequence: a signal can drive a parameter without changing the rhythm.

:::static
/*
Lane 1 is a cutoff staircase typed out by hand, one literal per note — the whole of what
a pattern language without signals can do. Lane 2 is appBoth, which shatters four kicks
into sixteen. Lanes 3-5 are `with(cutoff(curve))` over 4, 8 and 16 notes: the same curve,
sampled at whatever density the rhythm happens to be, note count untouched.
*/
showPatRoll("continuous-parameter")
:::fold open the output pane
displayOpen("main")
:::endfold

Hear it: sixteen hats a cycle, two cycles flat and then two with the gain following a sine. Same notes, same count, one parameter now a function of time. The hats are short noise bursts from the built-in patVoice rather than samples: a sampled hat rings for most of a second, and sixteen a cycle would blur into one sound with no level to follow.

Whose rhythm survives

When two patterns meet, the rhythm has to come from somewhere. There are exactly three answers, and Field spells them the way Tidal does; the bar marks the side the structure comes from.

:::static
showPatRoll("structure-choice")
:::fold open the output pane
displayOpen("main")
:::endfold

Kotlin will not accept /, < or > in an identifier, so division is `|over|` and the take-a-value family spells its arrow as an L or an R. The bar always keeps its Tidal meaning.

Rhythm transforms

Each lane applies one transform to the same four-step source:

:::static
// pat("a b c d") and seven transforms over four cycles, so the per-cycle ones are visible.
showPatRoll("rhythm-transforms")
:::fold open the output pane
displayOpen("main")
:::endfold

rev mirrors, euclid(3,8) spaces three onsets over eight slots, iter(4) advances a quarter each cycle, shuffle(4) permutes differently every cycle. Read the slow(2) lane across the bar lines: a b, then c d, then round again.

A rhythm that describes itself

A Euclidean rhythm needs its density decided in advance: euclid(3,8) is the answer to "three onsets, eight slots". kolakoski(16) answers a different question. The terms of the word 1 2 2 1 1 2 1 2 2 1 … are read as alternating on- and off-runs, so the figure's own run lengths spell out the word that made it — sixteen steps of it are x..xx.x..x..xx.x. In mini-notation it is a k inside the Euclidean brackets, and g asks for the other reading:

struct(kolakoski(16), pat("bd")) // the figure, as a bass drum
pat("bd(k16) hh*4") // the same, in a string
pat("bd(g16)") // each term as the gap to the next onset instead

:::static
// Two Kolakoski step counts, the gap reading, two Euclidean rhythms for contrast, and the
// alphabet {2,3} — all over two cycles.
showPatRoll("kolakoski")
:::fold open the output pane
displayOpen("main")
:::endfold

Read the first half of the kolakoski(32) lane against the whole of kolakoski(16): the same figure at half the width. Turning the step count up extends a Kolakoski rhythm instead of re-placing it, so the step count is a dial you can turn while the music plays. The two euclid lanes are there as the counter-example — euclid(3,16)'s first half is not euclid(3,8), because the step count is part of the question a Euclidean rhythm answers.

The gap reading — kolakoski(16, KolakoskiReading.GAPS), or (g16) in a string — reads the same terms as distances between onsets rather than run lengths, which fills the bar in to xx.x.xxx.xx.x.xx: eleven onsets in sixteen steps against the other reading's eight, and never more than one rest between hits.

The alphabet is a parameter too. kolakoski(16, a = 2, b = 3) is the self-describing word over {2,3} — 2 2 3 3 2 2 2 3 3 3 … — which has no run shorter than two, so that last lane never leaves a lone hit. kolakoskiInv and kolakoskiFull complete the family the way euclidInv and euclidFull do, and ->kolakoski is in RectSL for laying the figure out in space rather than in time.

Counting with one, placing with the other

The two figures answer different questions, which means they compose. Read the Kolakoski word as a sequence of densities rather than durations — each term saying how many hits go into the next group of slots — and let the Euclidean algorithm decide where inside the group those hits sit:

val counts = kolakoskiWord(8) // 1 2 2 1 1 2 1 2 — sums to 12
val hybrid = pat(counts.joinToString(" ") { "[bd($it,3)]" }) // [bd(1,3)] [bd(2,3)] …

Eight groups of three slots is a twenty-four slot bar carrying twelve onsets, which is exactly the density of euclid(12,24) — so the two lanes differ only in distribution. The Euclidean one is a flat alternation, because that is what maximal evenness over that density is. The hybrid bunches: the groups the word gives two hits to play them a slot apart, the ones it gives one sit alone, and the pattern of which is which is the word describing itself. Locally maximally even, globally self-describing.

:::static
// Twelve onsets in twenty-four slots, three ways: the hybrid, the maximally even
// figure of the same density, and the word read as run lengths instead.
val counts = kolakoskiWord(8)
val hybrid = pat(counts.joinToString(" ") { "[bd($it,3)]" })
showPatRollOf(
    "kolakoski x euclid" to hybrid,
    "euclid(12,24)" to struct(euclid(12, 24), pat("bd")),
    "kolakoski(24)" to struct(kolakoski(24), pat("bd")),
    title = "12 onsets in 24 slots, three ways",
    cycles = 2,
)
:::fold open the output pane
displayOpen("main")
:::endfold

The same rule run recursively is a rhythmic hierarchy: let the word say how many children a pulse has, let bjorklund place them on the parent's own slot grid, and let each child run until the next one so a level always tiles the bar. A count of one is then a pulse that holds rather than splits, and the level sizes come out as the word's own partial sums — one, one, two, three, four, seven. The whole scene, both figures and the audio, is the kolakoski_euclid transcript, openable from the welcome screen.

The shortest way to write a rhythm down

patCondense runs the parser backwards. Give it a rhythm and it hands back the shortest string that plays it.

patCondense("x ~ ~ x ~ x ~ ~").notation // x(3,8)
patCondense(kolakoskiMask(16)).notation // x(k16)
patCondense("bd [hh hh] sd [cp cp]").notation // bd hh*2 sd cp*2
pat("bd sd hh cp").rev().condense().notation // cp hh sd bd

The search covers the grammar the rest of this page describes: atoms and ~, _ and @n, [ ] at every divisor of a span, !n, *n, (p,s,r), (kN) and (gN), , and < >. It scores a candidate by the length of the string and accepts it only if it is exact, and exact is settled by playing it: every candidate goes back through pat and its events are compared to the target's. The one-slot-per-step spelling is always in the running, so the answer is never longer than that.

A rhythm with nothing in it comes back as itself. patCondense("a b c d e c a d") is a b c d e c a d, because no operator in the grammar shortens it.

:::static
// Four pairs: a rhythm above, its condensation below, played. Each pair has to coincide.
showPatRoll("condense")
:::fold open the output pane
displayOpen("main")
:::endfold

Three kinds of target are refused rather than approximated, and PatCondensation.refusal says which. A pattern that changes at random from cycle to cycle, such as [a|b|c] d or bd*8?0.4, has no period to condense. A pattern whose events cross a bar line has no bar to spell them in. And a pattern carrying parameters no atom can write down, like the pan that jux adds, would lose them.

Besides notation, a PatCondensation carries flat (the slot-by-slot spelling), compression (the ratio of the two lengths), structure (the constructs in the answer, read back off its parse) and limits (the search bounds, and which of them the run used).

This is also where the transcription path ends. patTranscribe recovers a step grid from audio and writes it out one slot per step; patCondense(transcription) turns that into a figure. The loop it belongs to is drawn in Audio render and analysis.

Time spans cycles, and events can cross bar lines

slow, fast, timeScale, density and mini-notation's /n are defined in absolute time, so pat("a b c d").slow(2) really does take two cycles: a b in the first, c d in the second.

The consequence is that an event can straddle a bar line. pat("a b c").slow(2) is three steps over two cycles, so b runs from 2/3 to 4/3, straight through it. A player asks for one cycle at a time, so it sees b twice, clipped both times, and would strike it twice if the events did not know better.

They do. Every event carries both the part you can see and the whole it was clipped from:

val crossing = pat("a b c").slow(2)

val lines = buildList {
    // One wide query: three notes, and b genuinely spans the bar line.
    add(
        "drawn    " + crossing.events(PatArc(PatQ.ZERO, PatQ.of(2))).joinToString("  ") { "${it.value}[${it.arc}]" },
    )
    // Cycle by cycle, b comes back twice — but only one fragment carries its onset.
    for (cycle in 0..1) {
        add(
            "cycle $cycle  " +
                crossing.events(PatArc(PatQ.of(cycle), PatQ.of(cycle + 1))).joinToString("  ") {
                    "${it.value}[${it.arc}]" + if (it.hasOnset) "" else " (continues)"
                },
        )
    }
    // And what actually gets played: three notes, each at its full length.
    add(
        "played   " + crossing.eventSequence(0).take(3).toList().joinToString("  ") { "${it.value}[${it.arc}]" },
    )
}
    .joinToString("\n")
println(lines)
display("<pre>" + lines + "</pre>")

hasOnset is the difference, and eventSequence, which every scheduling path uses, yields only the fragment that has one, widened back to the note's real length. A signal event has no whole at all (null), because a continuous curve has no note to begin; segment(n) is what gives it one.

Groove

Swing here is exact rational time, not a nudge in milliseconds: swing(4) puts every off-beat exactly a third of a subdivision late, and the pattern stays exactly quantised.

:::static
showPatRoll("groove")
:::fold open the output pane
displayOpen("main")
:::endfold

Eight hats a cycle, the same noise bursts: two cycles dead straight, then two swung.

chunk(n, f) applies a transform to a different 1/n of the bar each cycle, walking through all of them before it repeats. inside(n, f) is its cycle-invariant cousin: it slows down, transforms, and speeds back up, doing the same thing every cycle.

Harmony and voice leading

Chords are written root'name (c'maj7, a'min7), and everything that applies to a pattern applies to a pattern of chords.

voiceLead() chooses each chord's inversion and octave to minimise how far the voices have to move, without changing the harmony.

:::static
showPatRoll("voice-leading")
:::fold open the output pane
displayOpen("main")
:::endfold

Spelled from their own roots the progression spans 60–79 and leaps; voice-led it sits inside 53–64 with near-horizontal lines where common tones are held. 83 semitones of movement becomes 9, and the pitch-class sets are identical.

A rhythm as a curve — and as a graph you can fit

A pattern schedules events. Sometimes you want those events to trigger something other than a note, such as a continuous curve: an envelope to drive a parameter, a gesture to animate something with. patFn does that: each event becomes a little kernel, and the value at any time is the blend of the kernels around it. The kernel is chosen per atom, and its numbers are written in the atom itself:

So patFn("g:(0.9,0.18) g:(0.1,0.18)") is a two-bump gesture that repeats every cycle, and a Functions.Fn like any other, which means the whole Functions library applies to it.

From the inside it is a graph node, op = "pat", and every number in the pattern text is one of its leaves.

val gesture = patFn("g:(0.3,0.12) adsr:(0.8,0.01,0.08,0.4,0.2)", cps = 2.0, range = 0.9)
val node = gesture.graphNode()

val report =
    """
op        ${node.op}
source    ${node.strings["source"]}
knobs     ${node.children.joinToString("  ") { it.role }}
values    ${gesture.extractParameters().joinToString("  ")}

${gesture.graphText()}
"""
        .trimIndent()

println(report)
display("<pre>" + report + "</pre>")

Each atom's numbers are addressed by the role they play (atom0.sigma, atom1.attack) rather than by position, and cps is a knob too. That matters because Field's numeric leaves are exactly what the differentiable fitter tunes. You can hand a rhythm to fitGradient and have it recover the gesture's own numbers.

Below, the target is a two-bump gesture and the seed has the right structure with the wrong numbers: wrong heights, wrong widths. Adam moves the leaves until the curves coincide, and the fitted result comes back out as pattern text you can paste into a box:

with(Functions) {
    val target = patFn("g:(0.9,0.18) g:(0.1,0.18)", cps = 1.0, range = 0.9)
    val seed = patFn("g:(0.7,0.25) g:(0.3,0.12)", cps = 1.0, range = 0.9)

    val run = fitGradient(target, seed, domain = 0.0..2.0, iterations = 200, lr = 0.02, samples = 96)

    // A pat Fn runs to +infinity, so the plot is told which window to sweep.
    plot(target, 0.0..2.0, channel = "1 target", title = "target  g:(0.9,0.18) g:(0.1,0.18)")
    plot(run.fitted, 0.0..2.0, channel = "2 fitted", title = "fitted from a wrong-numbered seed")

    val report =
        """
    seed    ${seed.graphNode().strings["source"]}
    fitted  ${run.fitted.graphNode().strings["source"]}
    RMSE    ${run.initialError.f4} -> ${run.finalError.f4}
    """
            .trimIndent()
    println(report)
    display("<pre>" + report + "</pre>")
}

Both heights and both widths come back to three decimal places. What the fit cannot do is re-assign values between atoms: seed it with the two heights swapped and it stalls at about half the initial error, because getting to the answer needs a permutation and there is no downhill path through one. Tuning numbers is fitGradient's job; choosing which atom holds which number is evolve's.

Two smaller things. A number can be a %binding instead of a literal (g:(%loudness,0.2)), resolved from the box's variables each cycle: live, but for that reason not fittable, so such a pattern stays an ordinary opaque function. And because the knobs are graph children, you can graft a signal into one instead of a constant, which gives you a kernel width that drifts across the piece.

Where Field differs from Tidal

Four names to know if you are coming from Tidal:

fastcat exists as an alias for cat when you want the code to say which one it means.

Playing a pattern

eventSequence gives you the events in playing order. scheduled(cps) turns them into wall-clock times. respond {} calls you back as each one arrives.

pat("bd sd hh hh").respond(cps = 2.0) { event ->
    println("${event.start}s  ${event.value}  gain=${event.num("gain")}")
}

At two cycles a second, four steps land an eighth of a second apart. The onsets are times on Field's shared pattern clock, so they count from when that clock started rather than from 0. The pattern sets no gain, so num("gain") reads 0.

Because a note is scheduled at its onset and carries its whole length, a pattern that crosses bar lines plays correctly without the consumer knowing anything about cycles.

Where to go next

• The Pattern language starting point in the welcome screen opens the page's boxes (signals, structure choice, parameters, voice leading, groove and mini-notation), each with a live roll and most with audio. Edit any string and re-run.
• Sound plays patterns through samples and synths.
• Audio render and analysis renders a pattern to a file and transcribes audio back into one.