This is a list of special keys for events/pbind. These keys have additional functionality to do things like alter how the pattern is played, automate conversions between types, etc. Some of these only work in pbinds, and have no effect in events, and vice versa.
Some event keys are used to set standard parameters for the synth (i.e. instrument, out, etc). Additionally, cl-patterns will automatically convert between different units of measurement for data that represents the same property. For example, you can write a pattern that generates pitches based on midi note numbers with midinote. Then, in another key after that, you can use (pk :freq) to get the frequency of the note (which is automagically converted from the midinote value, as if you had used midinote-freq on it).
The type of event being played. Currently the following event types supported:
note- Play a note and release it after the number of beats specified by itssustainkey.rest- Don’t play anything during this event.set- Only set the parameters of a synth; don’t start or stop any notes. Note that this is only supported by thealsa-midibackend; for other backends, just provide the node/synth object as the pattern’s:instrument, like so:(defparameter *bass* (synth 'bass)) (pbind :instrument *bass* ...)
mono- Either start a synth if none is playing, or set the synth’s parameters if one is playing.tempo- Change the tempo of the clock and backend to the value specified by the event’stempokey.
In the future, the following additional event types (and others) will be supported as well:
play- Start playing a note. (known asonin SuperCollider ornote-onin MIDI)end- Release a note. (known asoffin SuperCollider ornote-offin MIDI)stop- Forcefully stop/free an object (node, buffer, etc) from the backend.backend- Send a backend-specific message to make it perform a non-standard action.
Name of the synth you want to trigger, or the node that you want to change parameters of.
Group to put the synth in on the server.
Currently only implemented for the SuperCollider backend. This is effectively an alias for to.
Bus that the synth should write its output to.
Volume of the synth.
Stereo panning of the synth’s output.
Set the clock’s tempo.
Time in beats before the next note starts.
also affects the hold time (sustain, in beats) of the note (see sustain / legato, below)
When the event should play, relative to the start of the pattern.
How long the synth is held before being released. sustain is an absolute time in beats for the note to be held, while legato is multiplied by dur to get the sustain time.
The timing offset of the event, in seconds, added onto the time when it would normally occur.
Various ways to specify the pitch of the synth.
The buffer that buffer-playing synths should play from.
A symbol or list of symbols naming backends that the event should be played on. If omitted, the event will be sent to all backends. Note that backends will usually ignore any events they don’t understand (i.e. the supercollider backend will not play any events whose instrument does not reference a known node or synthdef).
pbind supports a set of special keys that, during the initialization of the pbind, run a function which may alter the pbind’s pattern-pairs, or alter the pattern in another way. For example, a pbind that looks like this:
(defparameter *pat* (pbind :foo (pseq '(1 2 3))
:quant 4))…is effectively shorthand for this:
(defparameter *pat* (pbind :foo (pseq '(1 2 3))))
(setf (quant *pat*) 4)Here is a listing of all of the pbind special init keys:
Set the play-quant and end-quant of the pattern, which determine when the pattern is allowed to start or end playing, or when a pdef is allowed to swap to its new definition.
Set the play-quant of the pattern, which determines when the pattern is allowed to start playing.
Set the end-quant of the pattern, which determines when the pattern is allowed to end or swap to its new definition if redefined.
Set the loop-p slot of the pattern, which determines if the pattern should loop when it finishes playing.
Note that by default, patterns don’t loop, but pdefs do.
NOTE: Not implemented yet.
Set the condition of the pattern, which determines when the pattern is allowed to switch over to a new version of it after redefinition.
NOTE: Not implemented yet.
A function or list of functions to be run when the pattern ends or is stopped.
pbind also supports a set of special keys that effectively “wrap” the pbind in another type of pattern. For example, a pbind that looks like this:
(pbind :midinote (pseq '(60 62 64) 1)
:pdurstutter (pseq '(3 2 1) 1))…actually returns this pattern:
(pdurstutter (pbind :midinote (pseq '(60 62 64) 1))
(pseq '(3 2 1) 1))Here is a listing of all such keys:
Results in (pfor (pbind ...) value)
Deprecated alias for pfor.
Results in (pfin (pbind ...) value)
Results in (pfindur (pbind ...) value)
Results in (psync (pbind ...) value value)
or (psync (pbind ...) (first value) (second value))
Results in (pdurstutter (pbind ...) value)
Results in (ptrace (pbind ...)) when value is t
or traces the specified key when value is the name of a key.
Results in (pr (pbind ...) value)
Results in (pn (pbind ...) value)
Results in (pdef value (pbind ...))
Unlike other wrap keys or init keys, this key is always processed last regardless of where it appears in the pbind.
Results in (pmeta (pbind ...))
Results in (pparchain (pbind ...) value)
Results in (pchain (pbind ...) value) – effectively the same as the :embed key.
pbind’s last type of special keys are the process keys. Unlike the init and wrap keys, the values associated with these keys are processed for each output yielded by the pbind instead of only once during its initialization. Typically these are used to alter the outputs yielded. For example, this pbind:
(pbind :foo (pseq '(1 2 3))
:embed (pbind :bar (pseq '(9 8 7) 1)))…yields these events as its output:
((EVENT :FOO 1 :BAR 9)
(EVENT :FOO 2 :BAR 8)
(EVENT :FOO 3 :BAR 7))This is because the embed key embeds whatever its value’s outputs are into the pbind’s output events.
Here is a listing of all special process keys:
Embeds its value’s outputs into the pbind’s output events.
The beat number that this event occurs on in the pattern. This can be set as an alternative to dur or delta if you want to give an event’s start beat directly instead of its inter-onset time.
If you are setting this from a pattern, you need to make sure its values do not decrease with successive events otherwise event scheduling will fail.
pmeta is a “meta” pattern; instead of events triggering sounds directly, the events read by pmeta trigger other patterns.
the source pattern for this “step”.
set the duration of the source pattern (defaults to :inf, which causes the pattern to play to its end). similar to the sync key.
limit the duration of the source pattern.
set the duration of the source pattern with psync. similar to dur except you can provide a list instead, in which case it’s applied to psync’s arguments.
multiply the duration of each of the source pattern’s events.
fit a pattern to a number of beats, by getting up to *max-pattern-yield-length* events from the source pattern, then scaling their total duration.
stutter the outputs of the source pattern, a la pr.
inject each output from a pattern into the outputs of the source pattern.
inject one output per step into the outputs of the source pattern. on the next step, inject the next output into the outputs of the source pattern.
The following keys are planned for future implementation:
adjust the start or end points of the source pattern (i.e. to skip the first half, set :start to 0.5)
adjust the start or end points of the source pattern in number of beats (i.e. to end the pattern 2 beats early, set :end-beat to -2)
adjust the start or end points of the source pattern by skipping the first or last N events.
skip all of the source pattern’s events that return nil when applied to the specified function or pattern.
process each event from the source pattern with a function or another pattern.