std/patterns
Always in scope — no import required.
The core sequencing type and its combinators.
Pattern
Section titled “Pattern”A MIDI note pattern for sequencing. Construct with Sequence(...), Stack(...), Alternating(...), mini-notation, or pattern combinators.
Timing
Section titled “Timing”fn fast(factor: Number or Pattern) -> PatternSpeeds up the pattern by the given factor.
Parameters:
factor(Number | Pattern) — speed multiplier from 0.0001 to 10000 (> 1.0 = faster), or a pattern of them; a step outside that range, or a rest, silences that cycle
Returns: Pattern — the sped-up pattern, for chaining
fn slow(factor: Number or Pattern) -> PatternSlows down the pattern by the given factor.
Parameters:
factor(Number | Pattern) — speed divisor from 0.0001 to 10000 (> 1.0 = slower), or a pattern of them; a step outside that range, or a rest, silences that cycle
Returns: Pattern — the slowed-down pattern, for chaining
fn nudge(offsets: Array or Pattern) -> PatternShifts individual events by per-event offsets.
Parameters:
offsets(Array | Pattern) — offsets as a fraction of each event’s step, one per event
Returns: Pattern — the nudged pattern, for chaining
fn swing(amount: Number or Pattern, grid: Number) -> PatternDelays every second slot of a grid, like a drum machine’s swing: whatever plays on the off-beat 8th or 16th plays late, and what plays on the beat stays. A stack of drums swings as one groove. Notes between grid lines move with their pair and keep their order.
Example:
[bd*4, _ cp _ cp, ch*16].swing(0.1, 16) swings the hats; kicks and claps stay.
Parameters:
amount(Number | Pattern) — how late the second slot plays, as a fraction of a slot: 0 is straight, 0.33 a triplet feel, 0.5 dotted; or a pattern of them, one per cyclegrid(Number) — slots per cycle, an even number from 2 to 1024: 8 swings 8ths, 16 swings 16ths
Returns: Pattern — the swung pattern, for chaining
humanize
Section titled “humanize”fn humanize(amount: Number or Pattern) -> PatternAdds slight random timing variations for human feel.
Parameters:
amount(Number | Pattern) — maximum offset, as a fraction of each event’s step, or a pattern of them
Returns: Pattern — the humanized pattern, for chaining
Pitch & harmony
Section titled “Pitch & harmony”transpose
Section titled “transpose”fn transpose(semitones: Number or Pattern) -> PatternTransposes all notes by the given number of semitones.
Parameters:
semitones(Number | Pattern) — semitone offset (positive = up, negative = down), or a pattern of them
Returns: Pattern — the transposed pattern, for chaining
in_key
Section titled “in_key”fn in_key(key: Key) -> PatternResolves degree elements (^N, ^N:quality) to MIDI notes using a Key. MIDI and sample pitches pass through unchanged.
Parameters:
key(Key) — the key to resolve degrees against (e.g. Key(D4, “dorian”))
Returns: Pattern — the pattern with degrees resolved to notes, for chaining
quantize
Section titled “quantize”fn quantize(key: Key) -> PatternSnaps all MIDI pitches to the nearest tone in the key’s scale.
Parameters:
key(Key) — the key whose scale pitches are snapped to
Returns: Pattern — the quantized pattern, for chaining
Structure
Section titled “Structure”reverse
Section titled “reverse”fn reverse() -> PatternReverses the pattern playback order.
Returns: Pattern — the reversed pattern, for chaining
rotate
Section titled “rotate”fn rotate(steps: Number) -> PatternRotates the pattern by the given number of steps.
Parameters:
steps(Number) — number of positions to rotate
Returns: Pattern — the rotated pattern, for chaining
fn stack(other: Pattern) -> PatternStacks this pattern with another (polyphonic layering).
Parameters:
other(Pattern) — pattern to layer on top
Returns: Pattern — the combined polyphonic pattern, for chaining
concat
Section titled “concat”fn concat(other: Pattern) -> PatternConcatenates this pattern with another sequentially.
Parameters:
other(Pattern) — pattern to append
Returns: Pattern — the concatenated pattern, for chaining
degrade
Section titled “degrade”fn degrade(probability: Number) -> PatternRandomly removes events with the given probability.
Parameters:
probability(Number) — chance of removing each event (0.0-1.0)
Returns: Pattern — the degraded pattern, for chaining
fn at(index: Number) -> PatternReturns the element at the given index (for indexable patterns).
Parameters:
index(Number) — zero-based position
Returns: Pattern — the sub-pattern at index
euclid
Section titled “euclid”fn euclid(hits: Number, steps: Number, rotation: Number?) -> PatternApplies a Euclidean rhythm to the pattern.
Parameters:
hits(Number) — number of events to distributesteps(Number) — total steps in the rhythmrotation(Number) — offset rotation (optional, defaults to 0)
Returns: Pattern — the pattern with the Euclidean rhythm applied, for chaining
Transformation
Section titled “Transformation”fn map(func: Function) -> PatternTransforms each event using a function. The function receives the note value as a local variable.
Parameters:
func(Function) — fn(note) -> new_note
Returns: Pattern — the transformed pattern, for chaining
map_with_timing
Section titled “map_with_timing”fn map_with_timing(func: Function) -> PatternTransforms events with timing information.
Parameters:
func(Function) — fn(note, start, duration) -> new_note
Returns: Pattern — the transformed pattern, for chaining
Inspection
Section titled “Inspection”describe
Section titled “describe”fn describe() -> StringReturns a string description of the pattern structure.
Returns: String — a human-readable description of the pattern structure
length
Section titled “length”fn length() -> NumberReturns the number of events in cycle 0.
Returns: Number — the event count in cycle 0
fn iter() -> IteratorReturns an infinite iterator over pattern events.
Returns: Iterator — an infinite iterator over the pattern’s events
fn kind() -> StringReturns the concrete pattern kind (“Sequence”, “Stack”, “Fast”, etc.).
Returns: String — the concrete pattern kind
elements
Section titled “elements”fn elements() -> ArrayReturns sub-patterns as an array. Sequence/Alternating: individual element patterns. Stack/Cat: layer patterns. Combinators: the wrapped source pattern. Generative: empty array.
Returns: Array — the sub-patterns (empty for generative patterns)
Alternating
Section titled “Alternating”fn Alternating(...elements) -> PatternCreates an alternating pattern (one element per cycle).
Example:
Alternating(C4, E4, G4) cycles through notes.
Parameters:
elements(Array) — variadic elements, one played per cycle
Returns: Pattern — a pattern cycling through the elements
Sequence
Section titled “Sequence”fn Sequence(...notes) -> PatternCreates a sequential pattern that plays notes one after another.
Example:
Sequence(C4, E4, G4) plays notes in sequence.
Parameters:
notes(Array) — variadic notes to play in sequence
Returns: Pattern — a sequential pattern
fn Stack(...notes) -> PatternCreates a stacked/layered pattern (chord).
Example:
Stack(C4, E4, G4) plays a C major chord.
Parameters:
notes(Array) — variadic notes to layer simultaneously
Returns: Pattern — a stacked (polyphonic) pattern
euclid
Section titled “euclid”fn euclid(hits: Number, steps: Number, pattern: Pattern, rotation: Number = NUL) -> PatternCreates a Euclidean rhythm pattern. Distributes hits as evenly as possible across steps. The source’s events are dealt onto the hits in order, and wrap when there are more hits than events.
Example:
euclid(3, 8, [C4]) creates a classic 3-over-8 rhythm.
Parameters:
hits(Number) — number of events to place (>= 0)steps(Number) — total steps in the pattern (> 0)pattern(Pattern) — the pattern to apply at each hitrotation(Number) — offset rotation (optional, defaults to 0)
Returns: Pattern — the Euclidean rhythm pattern
fn viz(pattern: Pattern, cycles: Number = NUL, start_cycle: Number = NUL) -> NULDisplays an ASCII visualization of a pattern.
Parameters:
pattern(Pattern) — the pattern to visualizecycles(Number) — number of cycles to display (optional, defaults to 4)start_cycle(Number) — first cycle to display (optional, defaults to 0)
Returns: NUL — nothing; prints the visualization