Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

pulse

Pulse

Table with helper functions to ease creating rhythmic patterns.

examples:

-- using + and * operators to combine patterns
pulse.from{ 0, 1 } * 3 + { 1, 0 }

-- repeating, spreading and subsets
pulse.from{ 0, 1, { 1, 1 } }:repeat_n(4):spread(1.25):take(16)

-- euclidean patterns
pulse.euclidean(12, 16)
pulse.from{ 1, 0.5, 1, 1 }:euclidean(12)

-- generate/init from functions
pulse.new(8):init(1) --> 1,1,1,1,1,1,1,1
pulse.new(12):init(function() return math.random(0.5, 1.0) end )
pulse.new(16):init(scale("c", "minor").notes_iter())

-- generate pulses with note values
pulse.from{ "c4", "g4", "a4" } * 7 + { "a4", "g4", "c4" }

-- generate chords from degree values
pulse.from{ 1, 5, 6, 4 }:map(function(index, degree)
  return scale("c", "minor"):chord(degree)
end)

Functions

new(length : integer?, value : PulseTableValue | (index : integer) -> PulseTableValue?)

->Pulse

Create a new empty pulse table or a pulse table with the given length and value.

examples:

pulse.new(4) --> {0,0,0,0}
pulse.new(4, 1) --> {1,1,1,1}
pulse.new(4, function() return math.random() end)

from(...PulseTableValue | PulseTableValue[])

->Pulse

Create a new pulse table from an existing set of values or tables. When passing tables, those will be flattened.

examples:

pulse.from(1,0,1,0) --> {1,0,1,0}
pulse.from({1,0},{1,0}) --> {1,0,1,0}

copy(self : Pulse)

->Pulse

create a shallow-copy of the given pulse table (or self)

examples:

local p = pulse.from(1, 0)
local p2 = p:copy() --> {1,0}

distributed(steps : integer | table, length : integer, offset : integer?, empty_value : PulseTableValue?)

->Pulse

Create an new pulse table or spread and existing pulse evenly within the given length. Similar, but not exactly like euclidean.

Shortcut for pulse.from{1,1,1}:spread(length / #self):rotate(offset)

examples:

pulse.distributed(3, 8) --> {1,0,0,1,0,1,0}
pulse.from{1,1}:distributed(4, 1) --> {0,1,0,1}

euclidean(steps : integer | table, length : integer, offset : integer?, empty_value : PulseTableValue?)

->Pulse

Create a new euclidean rhythm pulse table with the given pulses or number of new pulses in the given length. Optionally rotate the contents too. Euclidean Rhythm

examples:

pulse.euclidean(3, 8)
 --> {1,0,0,1,0,0,1,0}
pulse.from{"x", "x", "x"}:euclidean(8, 0, "-")
 --> {"x","-","-","x","-","-","x","-"}

unpack(self : Pulse)

->... : PulseTableValue

Shortcut for table.unpack(pulse): returns elements from this pulse as var args.

examples:

local p = pulse.from{1,2,3,4}
local v1, v2, v3, v4 = p:unpack()

subrange(self : Pulse, i : integer, j : integer?, empty_value : PulseTableValue?)

->Pulse

Fetch a sub-range from the pulse table as new pulse table. When the given length is past end of this pulse it is filled up with empty values.

examples:

local p = pulse.from{1,2,3,4}
p = p:subrange(2,3) --> {2,3}
p = p:subrange(1,4,"X") --> {2,3,"X","X"}

take(self : Pulse, length : integer, empty_value : PulseTableValue?)

->Pulse

Get first n items from the pulse as new pulse table. When the given length is past end of this pulse its filled up with empty values.

examples:

local p = pulse.from{1,2,3,4}
p = p:take(2) --> {1,2}
p = p:take(4, "") --> {1,2,"",""}

clear(self : Pulse)

->Pulse

Clear a pulse table, remove all its contents.

examples:

local p = pulse.from{1,0}
p:clear() --> {}

init(self : Pulse, value : PulseTableValue | (index : integer) -> PulseTableValue, length : integer?)

->Pulse

Fill pulse table with the given value or generator function in the given length.

examples:

local p = pulse.from{0,0}
p:init(1) --> {1,1}
p:init("X", 3) --> {"X","X", "X"}
p:init(function(i) return math.random() end, 3)

map(self : Pulse, fun : (index : integer, value : PulseTableValue) -> PulseTableValue)

->Pulse

Apply the given function to every item in the pulse table.

examples:

local p = pulse.from{1,3,5}
p:map(function(k, v)
  return scale("c", "minor"):degree(v)
end) --> {48, 51, 55}

reverse(self : Pulse)

->Pulse

Invert the order of items in the pulse table.

examples:

local p = pulse.from{1,2,3}
p:reverse() --> {3,2,1}

rotate(self : Pulse, amount : integer)

->Pulse

Shift contents by the given amount to the left (negative amount) or right.

examples:

local p = pulse.from{1,0,0}
p:rotate(1) --> {0,1,0}
p:rotate(-2) --> {0,0,1}

push_back(self : Pulse, ...PulseTableValue[] | PulseTableValue)

->Pulse

Push a single or multiple items or other pulse contents to the end of the pulse. Note: When passing array alike tables or patterns, they will be unpacked.

examples:

local p = pulse.new()
p:push_back(1) --> {1}
p:push_back(2,3) --> {1,2,3}
p:push_back{4} --> {1,2,3,4}
p:push_back({5,{6,7}) --> {1,2,3,4,5,6,7}

pop_back(self : Pulse)

->PulseTableValue

Remove an entry from the back of the pulse table. returns the removed item.

examples:

local p = pulse.from({1,2})
p:pop_back() --> {1}
p:pop_back() --> {}
p:pop_back() --> {}

repeat_n(self : Pulse, count : integer)

->Pulse

Repeat contents of the pulse table n times.

examples:

local p = pulse.from{1,2,3}
patterns:repeat_n(2) --> {1,2,3,1,2,3}

spread(self : Pulse, amount : number, empty_value : PulseTableValue?)

->Pulse

Expand (with amount > 1) or shrink (amount < 1) the length of the pulse table by the given factor, spreading allowed content evenly and filling gaps with 0 or the given empty value.

examples:

local p = pulse.from{1,1}
p:spread(2) --> {1,0,1,0}
p:spread(1/2) --> {1,1}

tostring(self : Pulse)

->string

Serialze a pulse table for display/debugging purposes.

examples:

pulse.euclidean(3, 8):tostring() --> "{1, 0, 0, 1, 0, 0, 1, 0}"

Aliases

PulseTableValue

boolean | string | number | table

Valid pulse value in a pulse table