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.
A class that implements Pattern is a pattern too: it defines query(cycle) and has every combinator. A combinator, << or a parameter that takes a Pattern plays the instance as its fields are at that moment.
Writing a pattern
Section titled “Writing a pattern”fn query(cycle: Number) -> Note | Number | Rest | Array<Any> | Pattern?Required: each implementing class defines its own.
Returns what the pattern plays in one cycle.
class Rise implements Pattern { fn query(cycle) -> Note | Number | Rest | Array<Any> | Pattern? { return 60 + cycle % 12; }}Parameters:
cycle(Number) — the cycle to play, counting from 0
Returns: Note | Number | Rest | Array | Pattern? — the cycle’s notes: a Note or MIDI note number, an Array of them, a Pattern, or a Rest or NUL for silence
Timing
Section titled “Timing”fn fast(factor: Number | 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 | 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: Number | Array<Number> | Pattern) -> PatternShifts individual events by per-event offsets.
Parameters:
offsets(Number | Array | Pattern) — offsets as a fraction of each event’s step: one for every event, one per event, or a pattern of them
Returns: Pattern — the nudged pattern, for chaining
fn swing(amount: Number | 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 | 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 | 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 | Note | Array<Any>) -> PatternStacks this pattern with another (polyphonic layering).
Parameters:
other(Pattern | Note | Array) — pattern to layer on top; a note or an array of notes plays as a sequence
Returns: Pattern — the combined polyphonic pattern, for chaining
concat
Section titled “concat”fn concat(other: Pattern | Note | Array<Any>) -> PatternConcatenates this pattern with another sequentially.
Parameters:
other(Pattern | Note | Array) — pattern to append; a note or an array of notes plays as a sequence
Returns: Pattern — the concatenated pattern, for chaining
degrade
Section titled “degrade”fn degrade(probability: Number | Pattern) -> PatternRandomly removes events with the given probability.
Parameters:
probability(Number | Pattern) — chance of removing each event (0.0-1.0), or a pattern of them
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? = NUL) -> 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() -> Iterator<Event>Returns 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() -> Array<Pattern>Returns 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: Pattern | Note | Array<Any>) -> PatternCreates an alternating pattern (one element per cycle).
Example:
Alternating(C4, E4, G4) cycles through notes.
Parameters:
elements(Pattern | Note | Array) — the elements, one played per cycle; a lone Array is the list of elements itself
Returns: Pattern — a pattern cycling through the elements
Sequence
Section titled “Sequence”fn Sequence(...notes: Pattern | Note | Array<Any>) -> PatternCreates a sequential pattern that plays notes one after another.
Example:
Sequence(C4, E4, G4) plays notes in sequence.
Parameters:
notes(Pattern | Note | Array) — the notes, one after another; a lone Array is the list of notes itself
Returns: Pattern — a sequential pattern
fn Stack(...notes: Pattern | Note | Array<Any>) -> PatternCreates a stacked/layered pattern (chord).
Example:
Stack(C4, E4, G4) plays a C major chord.
Parameters:
notes(Pattern | Note | Array) — the notes or patterns to layer; a lone Array is the list of layers itself
Returns: Pattern — a stacked (polyphonic) pattern
euclid
Section titled “euclid”fn euclid(hits: Number, steps: Number, pattern: Pattern | Note | Array<Any>, 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 | Note | Array) — the pattern to apply at each hit; a note or an array of notes plays as a sequencerotation(Number?) — offset rotation (optional, defaults to 0)
Returns: Pattern — the Euclidean rhythm pattern
fn viz(pattern: Pattern | Note | Array<Any>, cycles: Number? = NUL, start_cycle: Number? = NUL) -> NULDisplays an ASCII visualization of a pattern.
Parameters:
pattern(Pattern | Note | Array) — the pattern to visualize; a note or an array of notes as a sequencecycles(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