turmeric
← All Guides

On this page

TidalCycles-like DSL for Turmeric - API Reference

Version: 1.0
Target: Phase 20+ (Post-algebraic effects)

This document provides complete API documentation for the TidalCycles-inspired pattern library.

Table of Contents

  1. Time Module (tidal/time.tur)
  2. Pattern Module (tidal/pattern.tur)
  3. Temporal Module (tidal/temporal.tur)
  4. Structural Module (tidal/structural.tur)
  5. Transform Module (tidal/transform.tur)
  6. Polyrhythm Module (tidal/polyrhythm.tur)
  7. Synth Module (tidal/synth.tur)
  8. Timing Module (tidal/timing.tur)
  9. Live Module (tidal/live.tur)
  10. Mini Module (tidal/mini.tur)
  11. Perf Module (tidal/perf.tur)

1. Time Module (tidal/time.tur)

Types

Type Description
Beats float - Time in beats (1.0 = one quarter note)
Seconds float - Time in seconds
Samples int64 - Time in samples at current sample rate

Functions

Function Signature Description
bpm->beats-per-sec (float) -> float Convert BPM to beats per second
bpm->sec-per-beat (float) -> float Convert BPM to seconds per beat
beats->sec (Beats, float) -> Seconds Convert beats to seconds at given BPM
sec->beats (Seconds, float) -> Beats Convert seconds to beats at given BPM
samples->sec (Samples, float) -> Seconds Convert samples to seconds at given sample rate
sec->samples (Seconds, float) -> Samples Convert seconds to samples at given sample rate

Tempo Tracking

Function Signature Description
make-tempo (float) -> Tempo Create tempo with BPM
tempo->beats (Tempo, Seconds) -> Beats Convert seconds to beats using tempo
tempo-beats-per-sec (Tempo) -> float Get beats per second from tempo

2. Pattern Module (tidal/pattern.tur)

Types

Type Description
Pattern<T> (fn [Beats] :T) - Function from time to value
NumPattern Pattern<float> - Numeric pattern

Constructors

Function Signature Description
const (T) -> Pattern<T> Constant pattern (always returns same value)
cycle (...T) -> Pattern<T> Cycle through values
phase (float = 1.0) -> NumPattern Phase position in cycle (0 to 1)

Macros

Macro Description
P (...exprs) -> Pattern<T> - Shorthand for const/cycle

Evaluation

Function Signature Description
pat-at (Pattern<T>, Beats) -> T Evaluate pattern at specific time

3. Temporal Module (tidal/temporal.tur)

Time Scaling

Function Signature Description
slow (float, Pattern<T>) -> Pattern<T> Slow down pattern by factor
fast (float, Pattern<T>) -> Pattern<T> Speed up pattern by factor
stretch (float, Pattern<T>) -> Pattern<T> Alias for slow
compress (float, Pattern<T>) -> Pattern<T> Alias for fast

Time Shifting

Function Signature Description
shift (Beats, Pattern<T>) -> Pattern<T> Shift pattern in time
rot (Beats, Pattern<T>) -> Pattern<T> Alias for shift

Time Mirroring

Function Signature Description
mirror (Pattern<T>) -> Pattern<T> Mirror pattern within cycle
rev (Pattern<T>) -> Pattern<T> Reverse time within cycle

Repetition

Function Signature Description
repeat (int, Pattern<T>) -> Pattern<T> Repeat pattern n times per cycle
once (Pattern<T>, T) -> Pattern<T> Play once, then return zero value

4. Structural Module (tidal/structural.tur)

Sequencing

Function Signature Description
seq (...Pattern<T>) -> Pattern<T> Sequence patterns
seq-n (...tuple<Pattern<T> float>) -> Pattern<T> Sequence with custom lengths

Stacking

Function Signature Description
stack (...Pattern<T>) -> Pattern<vec<T>> Stack patterns (play all simultaneously)
stack-with (fn[(vec<T>)]:U, ...Pattern<T>) -> Pattern<U> Stack with custom combiner

Convenience Combinators

Function Signature Description
sum (...NumPattern) -> NumPattern Sum all pattern values
multiply (...NumPattern) -> NumPattern Multiply all pattern values

Conditional Patterns

Function Signature Description
when (Pattern<bool>, Pattern<T>, T) -> Pattern<T> Play when condition is true
if-pat (Pattern<bool>, Pattern<T>, Pattern<T>) -> Pattern<T> If-then-else for patterns
every (int, Pattern<T>, T) -> Pattern<T> Play on every nth beat
nth (int, Pattern<T>, T) -> Pattern<T> Play on nth beats (using floor mod)

Euclidean Rhythm

Function Signature Description
euclid (int, int, int = 0) -> NumPattern Bjorklund's algorithm for evenly distributed hits

Pattern Selection

Function Signature Description
select (Pattern<int>, ...Pattern<T>) -> Pattern<T> Select pattern based on index
first-nonzero (T, ...Pattern<T>) -> Pattern<T> First non-zero value from patterns

5. Transform Module (tidal/transform.tur)

Arithmetic Transformations

Function Signature Description
add (NumPattern, NumPattern \| float) -> NumPattern Add pattern/constant
sub (NumPattern, NumPattern \| float) -> NumPattern Subtract pattern/constant
mul (NumPattern, NumPattern \| float) -> NumPattern Multiply pattern/constant
div (NumPattern, NumPattern \| float) -> NumPattern Divide pattern/constant

Range and Clamping

Function Signature Description
range (NumPattern, float, float, float, float) -> NumPattern Map value range
clamp (NumPattern, float, float) -> NumPattern Clamp to range

Randomness

Function Signature Description
jitter (Pattern<T>, float, T) -> Pattern<T> Add random jitter
rand-select (...Pattern<T>) -> Pattern<T> Randomly select from patterns
noise (float, float) -> NumPattern Perlin noise pattern
white-noise () -> NumPattern White noise pattern

Waveform Patterns

Function Signature Description
sine (float, float, float = 0.0) -> NumPattern Sine wave (freq, amp, phase)
square (float, float, float = 0.5) -> NumPattern Square wave (freq, amp, duty)
saw (float, float) -> NumPattern Sawtooth wave (freq, amp)
tri (float, float) -> NumPattern Triangle wave (freq, amp)

Envelopes

Function Signature Description
adsr (float, float, float, float, Pattern<bool> = (const true)) -> NumPattern ADSR envelope
ar (float, float, Pattern<bool> = (const true)) -> NumPattern Attack-Release envelope

6. Polyrhythm Module (tidal/polyrhythm.tur)

Polymeter

Function Signature Description
polymeter (float, Pattern<T>) -> Pattern<T> Pattern with different time signature

Polyrhythm

Function Signature Description
polyrhythm (Pattern<T>, float, Pattern<U>, float) -> Pattern<tuple<T U>> Two patterns with different cycle lengths

Nested Patterns

Function Signature Description
nest (Pattern<Pattern<T>>, float = 1.0) -> Pattern<T> Nested pattern (pattern of patterns)

Polyrhythm Combinators

Function Signature Description
stack-polymeter (...tuple<Pattern<T> float>) -> Pattern<vec<T>> Stack patterns with different meters
canon (Pattern<T>, int, float = 0.25) -> Pattern<vec<T>> Delayed copies (canon)
spread (Pattern<T>, int, float = 1.0) -> Pattern<vec<T>> Phase-shifted copies

Time Signature

Function Signature Description
timesig (Pattern<T>, ...tuple<float int>) -> Pattern<T> Pattern with changing time signatures

7. Synth Module (tidal/synth.tur)

Note Conversion

Function Signature Description
note->freq (int) -> float Convert MIDI note to Hz

Note Patterns

Function Signature Description
note-pattern (NotePattern, NumPattern = (const 100), NumPattern = (const 0.25), Pattern<bool> = (const true)) -> Pattern<map> Create note pattern

Types

Type Description
NotePattern Pattern<int> - Pattern of MIDI notes

Chord Patterns

Function Signature Description
chord-pattern (...NotePattern) -> NotePattern Create chord from note patterns

Arpeggio Patterns

Function Signature Description
arp-pattern (Pattern<vec<int>>, float = 4.0) -> NotePattern Arpeggiate chord

Drum Patterns

Function Signature Description
drum-pattern (...tuple<int float>) -> Pattern<map> Create drum pattern from hits
kick (vec<Beats>, ...kwargs) -> Pattern<map> Bass drum pattern
snare (vec<Beats>, ...kwargs) -> Pattern<map> Snare drum pattern
hat (vec<Beats>, ...kwargs) -> Pattern<map> Hi-hat pattern
cymbal (vec<Beats>, ...kwargs) -> Pattern<map> Cymbal pattern

Pattern to Synth Mapping

Function Signature Description
pat->param (NumPattern, Synth, cstr) -> unit Map pattern to synth parameter
pats->params (Synth, ...tuple<cstr NumPattern>) -> unit Map multiple patterns to parameters

Pattern Players

Function Signature Description
pattern-synth (ScscmSession, cstr, ...tuple<cstr NumPattern>, float) -> Synth Create synth with pattern-driven parameters
make-player (ScscmSession, cstr, Pattern<map>, float) -> PatternPlayer Create pattern player
player-start (PatternPlayer) -> unit Start pattern player
player-stop (PatternPlayer) -> unit Stop pattern player
player-update (PatternPlayer, Pattern<map>) -> PatternPlayer Update player with new pattern
swap-patterns (PatternPlayer, map<cstr Pattern<float>>) -> PatternPlayer Swap multiple patterns

8. Timing Module (tidal/timing.tur)

Beat Clock

Type Description
BeatClock Struct with bpm, sample-rate, samples-per-beat
Function Signature Description
make-beat-clock (float, float) -> BeatClock Create beat clock
clock->beats (BeatClock, Samples) -> Beats Convert samples to beats
clock->samples (BeatClock, Beats) -> Samples Convert beats to samples

Audio Pattern

Function Signature Description
audio-pattern (Pattern<float>, BeatClock) -> (fn [Samples] :float) Create audio-rate pattern
mix-audio-patterns (...AudioPattern) -> AudioPattern Mix audio patterns

Pattern Scheduler

Type Description
PatternScheduler Struct with clock, patterns, synths, events
Function Signature Description
make-pattern-scheduler (BeatClock) -> PatternScheduler Create scheduler
schedule-pattern (PatternScheduler, Pattern<map>, cstr, Beats) -> NodeID Schedule pattern
schedule-event (PatternScheduler, NodeID, Pattern<map>, Beats) -> unit Schedule event
process-events (PatternScheduler, Beats) -> unit Process scheduled events

9. Live Module (tidal/live.tur)

Live Session

Type Description
LiveSession Struct with bpm, patterns, state
Function Signature Description
make-live-session (float) -> LiveSession Create live session
session-set-pattern (LiveSession, cstr, Pattern<T>) -> LiveSession Set pattern in session
session-get-pattern (LiveSession, cstr) -> Pattern<T> Get pattern from session
session-remove-pattern (LiveSession, cstr) -> LiveSession Remove pattern from session

Pattern Replacement

Function Signature Description
player-update (PatternPlayer, Pattern<T>) -> PatternPlayer Update player pattern
swap-patterns (PatternPlayer, map<cstr Pattern<float>>) -> PatternPlayer Swap multiple patterns

Pattern Hot-Reloading

Function Signature Description
watch-pattern (cstr, ScscmSession, cstr, float) -> PatternPlayer Watch file for pattern changes
eval-pattern (cstr) -> Pattern<T> Evaluate pattern from string

Stateful Patterns

Type Description
StatefulPattern<T> Struct with pattern, state
Function Signature Description
make-stateful-pattern (T, fn[T Beats] : tuple<T Pattern<T>>) -> StatefulPattern<T> Create stateful pattern
step-stateful (StatefulPattern<T>, Beats) -> tuple<T StatefulPattern<T>> Step stateful pattern
counter-pattern (int) -> StatefulPattern<int> Counter pattern (mod n)

Session State Patterns

Function Signature Description
state-pattern (cstr, fn[T] : Pattern<U>) -> Pattern<U> Pattern from session state
updating-pattern (cstr, T, fn[T Beats] : tuple<T U>) -> Pattern<U> Pattern that updates state

10. Mini Module (tidal/mini.tur)

Tokenization

Type Description
MiniToken Enum: :num, :op, :paren-open, :paren-close, :bracket-open, :bracket-close
Function Signature Description
mini-tokenize (cstr) -> vec<tuple<MiniToken cstr>> Tokenize mini-notation string

Parsing

Function Signature Description
parse-mini (cstr) -> Pattern<float> Parse mini-notation to pattern
mini-parse (cstr) -> Pattern<float> Parse mini-notation expression
mini-parse-tokens (vec<tuple<MiniToken cstr>>) -> Pattern<float> Parse tokens to pattern

Macros

Macro Description
s (cstr) -> Pattern<float> - Shorthand for parse-mini
d (cstr) -> Pattern<map> - Shorthand for parse-drums
n (cstr) -> Pattern<float> - Shorthand for parse-notes

Drum Notation

Function Signature Description
parse-drums (cstr) -> Pattern<map> Parse drum mini-notation

Operators

Function Signature Description
mini-apply-op (cstr, NumPattern, NumPattern) -> NumPattern Apply operator to patterns

11. Perf Module (tidal/perf.tur)

Pattern Caching

Function Signature Description
cached (Pattern<T>, int = 1024) -> Pattern<T> Cache pattern results

Pattern Inlining

Function Signature Description
inline-pattern (Pattern<T>) -> Pattern<T> Inline pattern for performance

Pattern Fusion

Function Signature Description
fuse-pattern (Pattern<T>) -> Pattern<T> Fuse consecutive operations

Benchmarking

Function Signature Description
benchmark-pattern (Pattern<T>, int, Beats) -> BenchmarkResult Benchmark pattern evaluation
measure-latency (fn[]:T, int) -> float Measure function latency
measure-throughput (fn[]:T, int) -> float Measure function throughput

Zero-Allocation Patterns

Function Signature Description
zero-alloc-pattern (Pattern<T>) -> Pattern<T> Create zero-alloc pattern

Main Module (tidal/tidal.tur)

The main module re-exports all functions from submodules:

(import tidal)  ;; Imports all tidal/* modules

Convenience Functions

Function Signature Description
play (ScscmSession, cstr, cstr, float) -> PatternPlayer Play mini-notation pattern
d1 (ScscmSession, cstr, Pattern<map>, float) -> PatternPlayer Set default pattern (d1)
hush (PatternPlayer) -> PatternPlayer Silence player (hush)

Index

By Category

Generated for Turmeric project - TidalCycles-like DSL API Reference