cycle

Global

Functions

cycle(input : string)

->Cycle

Create a note sequence from a Tidal Cycles mini-notation string.

cycle accepts a mini-notation as used by Tidal Cycles, with the following differences:

  • Stacks and random choices are valid without brackets (a | b is parsed as [a | b])
  • Operators currently only accept numbers on the right side (a3*2 is valid, a3*<1 2> is not)
  • : - Sets the instrument or remappable target instead of selecting samples Tidal Cycles Reference

examples:

--A chord sequence
cycle("[c4, e4, g4] [e4, g4, b4] [g4, b4, d5] [b4, d5, f#5]")

--Arpeggio pattern with variations
cycle("<c4 e4 g4> <e4 g4> <g4 b4 d5> <b4 f5>")

--Euclidean Rhythms
cycle("c4(3,8) e4(5,8) g4(7,8)")

--Map custom identifiers to notes
cycle("bd(3,8)"):map({ bd = "c4 #1" })

Aliases

CycleMapFunction

(context : CycleMapContext, value : string) -> CycleMapNoteValue

CycleMapGenerator

(context : CycleMapContext, value : string) -> CycleMapFunction

CycleMapNoteValue

Note | NoteValue | NoteValue[]

NoteValue

string | number | NoteTable | nil

PlaybackState

"running" | "seeking"

-- - *seeking*: The emitter is auto-seeked to a target time. All results are discarded. Avoid
--   unnecessary computations while seeking, and only maintain your generator's internal state.
-- - *running*: The emitter is played back regularly. Results are audible.
PlaybackState:
    | "seeking"
    | "running"

Cycle

Functions

map(self, map : CycleMapFunction | CycleMapGenerator | { })

->Cycle

Map names in in the cycle to custom note events.

By default, strings in cycles are interpreted as notes, and integer values as MIDI note values. Custom identifiers such as "bd" are undefined and will result into a rest, when they are not mapped explicitly.

examples:

--Using a static map table
cycle("bd [bd, sn]"):map({
  bd = "c4",
  sn = "e4 #1 v0.2"
})

--Using a static map table with targets
cycle("bd:1 <bd:5, bd:7>"):map({
  -- instrument #1,5,7 are set additionally, as specified
  bd = { key = "c4", volume = 0.5 },
})

--Using a dynamic map function
cycle("4 5 4 <5 [4|6]>"):map(function(context, value)
  -- emit a random note with 'value' as octave
  return math.random(0, 11) + value * 12
end)

--Using a dynamic map function generator
cycle("4 5 4 <4 [5|7]>"):map(function(init_context)
  local notes = scale("c", "minor").notes
  return function(context, value)
    -- emit a 'cmin' note arp with 'value' as octave
    local note = notes[math.imod(context.step, #notes)]
    local octave = tonumber(value)
    return { key = note + octave * 12 }
  end
end)

--Using a dynamic map function to map values to chord degrees
cycle("1 5 1 [6|7]"):map(function(init_context)
  local cmin = scale("c", "minor")
  return function(context, value)
    return note(cmin:chord(tonumber(value)))
  end
end)

Aliases

CycleMapFunction

(context : CycleMapContext, value : string) -> CycleMapNoteValue

CycleMapGenerator

(context : CycleMapContext, value : string) -> CycleMapFunction

CycleMapNoteValue

Note | NoteValue | NoteValue[]

NoteValue

string | number | NoteTable | nil

PlaybackState

"running" | "seeking"

-- - *seeking*: The emitter is auto-seeked to a target time. All results are discarded. Avoid
--   unnecessary computations while seeking, and only maintain your generator's internal state.
-- - *running*: The emitter is played back regularly. Results are audible.
PlaybackState:
    | "seeking"
    | "running"

CycleMapContext

Context passed to 'cycle:map` functions.

Properties

playback : PlaybackState

Specifies how the cycle currently is running.

channel : integer

channel/voice index within the cycle. each channel in the cycle gets emitted and thus mapped separately, starting with the first channel index 1.

step : integer

Continues step counter for each channel, incrementing with each new mapped value in the cycle. Starts from 1 when the cycle starts running or after it got reset.

step_length : number

step length fraction within the cycle, where 1 is the total duration of a single cycle run.

trigger_note : integer?

Note value that triggered, started the rhythm, if any.

trigger_volume : number?

Note volume that triggered, started the rhythm, if any.

trigger_offset : integer?

Note slice offset value that triggered, started the rhythm, if any.

inputs : table<string, boolean | string | number>

Current input parameter values, using parameter ids as keys and the actual parameter value as value.

beats_per_min : number

Project's tempo in beats per minutes.

beats_per_bar : integer

Project's beats per bar setting.

samples_per_sec : integer

Project's sample rate in samples per second.

Aliases

PlaybackState

"running" | "seeking"

-- - *seeking*: The emitter is auto-seeked to a target time. All results are discarded. Avoid
--   unnecessary computations while seeking, and only maintain your generator's internal state.
-- - *running*: The emitter is played back regularly. Results are audible.
PlaybackState:
    | "seeking"
    | "running"