A console turns buttons into light. You press a key, and an effect plays on your fixtures; you tap a beat, and a running effect pulses with it; you hold a key, and a parameter rises while you hold it. Consoles play live, from the session clock, instead of from a timeline.
A console is a sequence built as you play: every action is an edit at the current time. Playing a clip places it from now for its length, starting and stopping a clip places it again and again for its length between the two, a mark goes into a collection now, and setting a parameter changes its value from now on. Its layers and operator graph are a sequence's.
Every device that plays a console runs the same Donder runtime, so only your button presses travel: the Preview, live E1.31 or Art-Net output and Donder controllers receive the same presses and each plays the console itself.
A console never plays on top of a sequence. Stop the sequence, then perform.
Input devices
An InputDevice is something you play from: the computer keyboard, a MIDI
device such as a piano keyboard, a pad controller or a box of knobs, or any
program or app that sends OSC.
Each of its controls has a name you choose and the input it reads. A Button
is pressed or released; an Axis is a position from 0 to 1.
InputDevice keyboard {
description: "The computer keyboard.",
driver: Keyboard,
controls: [
Button { name: kick, description: none, input: Key { code: KeyA } },
Button { name: tap, description: "Tap along to the beat.", input: Key { code: Space } },
],
}
Keys use the physical key names browsers use (KeyA, Digit1, Space,
ShiftLeft, ArrowUp, Numpad0), so a binding stays on the same key whatever
your keyboard layout.
A MIDI device reads the MIDI ports whose name contains its port, ignoring
case, or every port when port is none. Its buttons read notes, held from
note on to note off, and control changes, held at 64 and above as a sustain
pedal is. A button reading Notes { low, high, channel } is a range of notes,
a piano's keyboard, where every note is its own press; a single note is a range
whose low is its high. Its axes read control changes and the pitch bend
wheel.
Every MIDI input reads one channel, numbered 1 to 16 as devices label them,
or every channel when channel is none. A controller that sends its pads on
channel 10 and its keys on channel 1 can then give the same note numbers to a
pad and a key.
InputDevice piano {
description: "The stage piano and its pedals.",
driver: Midi { port: "Digital Piano" },
controls: [
Button { name: keys, description: "All 88 keys.", input: Notes { low: 21, high: 108, channel: none } },
Button { name: sustain, description: none, input: ControlChange { number: 64, channel: none } },
Axis { name: hue, description: "The first knob.", input: ControlChange { number: 21, channel: 1 } },
Axis { name: bend, description: none, input: PitchBend { channel: none } },
],
}
Notes are MIDI note numbers, 0 to 127, with middle C at 60 and a full piano from 21 to 108; control changes are 0 to 119. A struck note carries how hard it was struck, its velocity. Donder connects to a device's ports when you start performing, and to ports plugged in while you perform; the Perform bar shows the ports it reads.
An OSC device listens for OSC messages
sent over UDP to its port, on every network interface, so a phone app such as
TouchOSC, a Max or Pure Data patch, or an analysis script on another computer
can play the console. Its controls read an Address, matched exactly. A button
is pressed when a message's first argument is above 0 and released at 0, and a
message with no arguments presses and releases it at once, which suits marks
and fixed-length plays. An axis reads the first argument, running from low to
high, so a script can send a tempo in beats per minute or a pitch in hertz as
it is.
InputDevice harmony {
description: "Chord analysis from the listener script.",
driver: Osc { port: 9000 },
controls: [
Button { name: chord_change, description: none, input: Address { path: "/chord/change" } },
Axis { name: tempo, description: none, input: Address { path: "/tempo", low: 60.0, high: 180.0 } },
],
}
An address is a / and then printable characters other than spaces and OSC's
pattern characters *?[]{}#,. Bundles play their messages in order, stamped
when they arrive. Any computer on the network can send to the port while you
perform. Two OSC devices of a setup listen on different ports; the Perform bar
shows the ports listening, or why one could not be opened.
A device's control names are unique, and no two controls read the same input;
two MIDI controls may read the same note or control change only on different
channels.
The setup lists the input devices you have, next to its controllers:
input_devices: [devices.keyboard]. A console can only use devices the active
setup lists. Device files are ordinary documents: share one, and anyone with the
same hardware can copy it into their project.
In the GUI a control is bound by using it. + adds a control and listens, and the learn button on a row, which shows while the pointer is over it, listens again. The next key, note, knob or OSC message sets the input and the kind: a note is a button, a control change or pitch bend is an axis, and an OSC message with no value or a value of 0 or 1 is a button, while any other value makes an axis from 0 to 1. A MIDI control reads any channel unless another control already reads that input, in which case it reads the channel the message came on. Selecting a note box of a range and pressing a key sets that end of the range. Esc stops listening. A performance that already reads the device supplies the messages; otherwise Donder opens the device, and starting a performance ends learning.
Consoles
A console has the same layers and operator graph as a sequence, plus what plays live:
- Live mark collections (
LiveMarks): start empty each session and gain a mark each time aMarkaction runs. Any effect with a marks parameter can read one, so effects such as MarkPulse react to the beat you tap. - Clips (
ConsoleClip): a sequence clip without a start or a duration: a name, a layer, a fixture or group, a scope, an effect and its parameters, and the parameters each copy takes from how it was played (see Played values). Actions name the clip they play. always(Always { clip, length }): clips that play from the session's start, starting again each timelengthends.- Events (
On { event, actions }): what a control does. The event isPress { control }orRelease { control }of a button, orMove { control }of an axis, and its actions run in order. Any number ofOns may name the same event. Pressing a button that is already held, as a computer key repeats, does nothing.
An action is one of:
Play { clip, copies, length }plays a copy of the clip for its length, on top of the copies already playing: up tocopies, 1 to 16, play at once, and when they all play the oldest is reused.lengthisFixed { duration }orScaled { by, shortest, longest }, wherebyisVelocity(how hard the press was; a computer key presses at 1) orAxis { control }(where an axis is now; one not yet moved reads 0), mapped fromshortestat 0 tolongestat 1. The length is read once when the copy starts; later changes do not affect copies already playing.Start { clip, length }plays one copy until it is stopped, starting it again from its beginning each timelengthends. Pressing again while the clip plays does nothing.Stop { clip }stops every playing copy of the clip.Toggle { clip, length }starts the clip, asStartdoes, if no copy plays, and otherwise stops it.Mark { into }adds a mark to a live mark collection.Set { param, window }writes the event's value into a parameter of a clip (ClipParam { clip, param }) or of an operator node of the console's graph (NodeParam { node, param }): an axis's position onMove, the velocity onPress, and 0 onRelease. The value's0..1, throughwindow(a(low, high)part of0..1, so(0.0, 0.7)makes the knob's top 70% of the range), maps onto the parameter's declared range, as sequence automation does, and the parameter rests at the window's low end, where an axis not yet moved or a released button puts it, until the firstSet. One control sets a parameter, by any of its events, and a played value cannot also set it.
A clip is played either by Play actions or by Start, Toggle and always,
not both; Stop stops either. A Move runs only Set actions.
Every copy plays for a length, and its effect's duration and progress
count over that length: a held or always clip's progress runs from 0 to 1
in each pass and starts again, so a chase moves at its own speed however long
the clip is held.
The only state a console keeps is which copies of each clip play, its live
marks and the values Set actions have written.
Editing a console
The GUI lists every button of the setup's input devices, edge to edge like a
sequence's grid, with the actions it runs when pressed and when released. +
in a cell adds an action. Playing an effect adds the effect and its action
together, as one edit: for a moment (a Play of one second), while held
(Start on the press and Stop on the release) or toggled. A new held,
toggled or always-playing effect repeats every 4 seconds. Selecting an
action opens it in the side panel, as a sequence's clips open, with its copies
and length, or how often it repeats, and the effect it plays: layer, target, scope, effect type and
parameters. Knobs (axes) are not rows of the grid: a parameter of an effect, or
of an operator in the layers and operators editor, picks what sets it live from
its own row: a knob, by its position, or, for an effect, how the press that
started each copy was played. Removing an action removes the
effect it played when nothing else plays or holds it, with the stop that went with
it. Effects that play from the session's start are listed above the controls,
and the side panel of one sets how often it repeats. A mark
action's panel names the effects that read its collection.
Played values
A clip's played values set parameters of each copy from how the press that
started it was played, so every note sounds its own way:
played: [
PlayedValue { param: level, from: Velocity, window: (0.2, 1.0) },
PlayedValue { param: hue, from: PitchClass, window: (0.0, 1.0) },
],
Velocity: how hard the note was struck; a computer key or a pedal plays at 1.PitchClass: the note's name, C at 0 up the chromatic scale to B at 11/12, whatever its octave.
The value's 0..1, through window, maps onto the parameter's declared range,
as with automation, and the parameter is a float, int, bool, enum or curve. A
clip with played values is started only by Press events, never always, and
plays PitchClass only when every control that starts it reads notes. A
parameter a Set writes cannot also be played. Played from a range of notes,
Play is polyphonic: each note takes a copy and plays it with its own values.
The starter's jam console
The starter project includes consoles/jam.data.donder, played from
input_devices/keyboard.data.donder. Its background clip plays always: a
MarkPulse on every output that pulses on each beat of the live beat
collection. A plays a 0.4 s flash on top of up to four others, S starts the
wash, repeating every 4 s, and releasing S stops it, Space taps a beat into beat, and D sets the
decay_seconds of the background to its highest on press and its lowest on
release, lengthening the background's pulses while it is held.
Effects a console plays are prepared when you start performing, once, with a
pool of copies for each clip: as many as its largest copies, or one for a clip
that is started, toggled or always playing. An effect that loops over the marks
of a collection it reads cannot read a live collection, because a live
collection's length is not known in advance; Donder reports this when it checks
the project.
Performing
Choose Perform for a console: in the project's console list, or by
right-clicking the console's document in the Explorer. Donder prepares the
console on the active setup, starts its always clips and starts the session
clock. The Perform bar shows the console, the elapsed time and which buttons you
hold, with toggles for live output and the Preview, and Stop.
Live output plays a performance on every controller of the setup. E1.31 and
Art-Net controllers receive the frames Donder renders. Donder controllers play
the console themselves: Donder sends each one its part of the console, starts
it at the session's place on the editor's clock, and sends it your presses over
the network, which it plays as they arrive. Effects you start on a Donder
controller can begin a few milliseconds after the same effect on an E1.31 or
Art-Net controller, or on another Donder controller, as Wi-Fi delivers them;
always effects stay together. A controller that comes onto the network
while you perform joins the performance where it is. One that loses its
connection releases the buttons you hold on it, and joins again with
everything you played when the connection returns.
Edits to the console you are performing, or to an input device it reads, apply
at once: Donder arms the console again on the same clock, replays your inputs
into it, so held buttons, marks added and parameters set carry over, and keeps
the MIDI and OSC ports it has open. always effects start again. Each Donder
controller whose part changed takes the new console, as a delta of the one it
holds when that is small, or whole, going dark while it loads, otherwise.
While you perform, the console's keys go to the console before any editor
shortcut, both in the main window and in the Preview window. Keys typed into a
text field stay in the field. Releasing focus releases every held button, which
runs their Release events. A session lasts up to about 71 minutes, the
playback clock's range.