A Donder project is a folder of documents written in one language. Data
documents describe what the editor edits: the project, setups, controllers,
layouts, fixtures, patches, sequences, curves and gradients. Script documents
hold effects and operators in the effect language. Both
kinds share one lexer and one set of literal rules. Project IO loads the
documents into the typed DonderProject, which is authoritative from then on.
Goals
- Exact correspondence with the editor. A valid data document is exactly one editor state, and every editor state is exactly one data document. Every field the text holds, including names and descriptions, can be shown and edited in the GUI, and the GUI stores nothing the text omits.
- Canonical tokens. A state has exactly one valid sequence of tokens. Whitespace and line breaks are the only freedom, and saving normalizes them. Saving therefore never changes a token you wrote: not a number's spelling, not the order of fields, not an explicit value.
- One schema. The Rust document types in
crates/donder-project-io/src/document/types.rsare the schema. Their#[derive(Data)](crates/donder-data-derive) generates decoding, encoding and a shape description from the same field lists.
Documents
| Kind | File | Contains | Comments |
|---|---|---|---|
| Data | *.data.donder | Data declarations; the root is project.data.donder | No |
| Script | *.donder | Effects and operators, with document-local functions | -- line comments |
A data document may mix declaration types, for example a sequence with the curves it uses. A script may declare effects, operators or both.
Data documents have no comments, because comments have no place in the editor
state and the GUI could not keep them. Objects that deserve prose have a
description field instead, which the GUI shows and edits. Scripts keep
comments: the GUI never rewrites code, so their source text is kept exactly.
Lexical structure
Shared by both kinds unless noted.
- Whitespace separates tokens and is otherwise insignificant.
- Comments (scripts only):
--to the end of the line. In a data document--is an error. - Identifiers:
[A-Za-z_][A-Za-z0-9_]*. Names of objects, fields and parameters aresnake_case; types, variants and enum options arePascalCase. The casing is a rule, not a convention: the wrong case is an error, sowhole_targetandWholeTargetcannot both appear. - Keywords in data documents:
import,from,true,falseandnone.importandfromare field names where a field name is expected, as in an edge'sfrom:. Scripts reserve their declaration and statement words (effect,operator,fn,let,guard,if,else,for,in,match) and their member words where a member starts (param,input,sample). - Integers:
0,42,-7. No leading zeros, no+, no separators. - Floats: always contain a
.with digits on both sides:1.0,0.35,-2.5. A data float must be the shortest spelling that reads back as the same 32-bit float, so0.6is valid and0.60or0.6000000238418579is an error with a fix to0.6. Data has no exponents, NaN or infinity, and never accepts an integer where a float is expected (1is an error; write1.0). Scripts keep their int-to-float widening, because the GUI never reprints code. - Durations (data): a non-negative decimal number of seconds followed by
s:1s,0.25s,249.753832s. Exact to the nanosecond, so at most nine decimals, with no trailing zeros:1.50sand1.0sare errors with fixes. - Distances (data): meters followed by
m, exact to the micrometer, so at most six decimals and no trailing zeros:0m,0.35m,-1.2m. - Colors:
#and six hexadecimal digits. Data colors are lowercase:#38bdf8, and#38BDF8is an error with a fix. - Strings: double-quoted UTF-8 with escapes
\",\\,\nand\t; nothing else needs escaping. No multi-line literal; use\n. - Paths (data):
<relative path>in imports and asset fields:<effects/standard.donder>. Paths are relative to the project root, use/, and may contain any character except>,<and line breaks.
Data grammar
document = import* declaration*
import = "import" name "from" path ("," path)* ";"
declaration = TypeName name record_body
record_body = "{" (field ("," field)* ","?)? "}"
field = name ":" value
value = literal | reference | list | tuple | record | named | map
record = TypeName record_body? -- a fieldless variant is its bare name
named = TypeName name record_body -- an owned collection member
list = "[" (value ("," value)* ","?)? "]"
tuple = "(" value "," value ("," value)* ")"
map = "{" (name ":" value ("," name ":" value)* ","?)? "}"
reference = name ("." name)*
literal = integer | float | duration | distance | color | string | path
| "true" | "false" | "none"
The schema, not the grammar, decides which form each field takes. Records and
variants both start with their type name: a field of type Port holds
Port { ... }, and a field whose type has several variants holds whichever one
it is, such as E131 { ... } or Donder { ... }. A variant without fields is
its bare name, Multicast, never Multicast {}; a record always has its
braces. An effect parameter's enum option is written the same way: Forward,
or FixedTime { revolution_time_ms: 250.0 } for an option with fields. A map
appears only for effect and operator parameter values, whose keys are the
definition's parameter names.
Everything is explicit. Every field of a record is written, in schema order.
An optional value is the value or none. Because nothing is implied, an explicit
value can never be dropped by a save, and a document reads fully without knowing
any defaults. Writing fields out of order is an error, never a silent
reordering. Lists keep their order, which is meaningful and is the GUI's order.
A trailing comma is accepted everywhere, and the printer writes one after the last item of every multi-line record, map or list.
The parser recovers at field, item and declaration boundaries, so one document reports every syntax error with its range. A record cut short by a syntax error does not also report the fields the error swallowed.
Names and references
Every object other objects refer to has a name: setups, controllers, ports, input devices, controls, layouts, fixtures, groups, fixture definitions, fixture shapes, patches, sequences, layers, clips, mark collections, graph operator nodes, consoles, console clips, live mark collections, curves and gradients. The name is the object's only identity: references use it, and the GUI shows and edits it. Objects nothing refers to (routes, automation clips, edges, console events) have no name. No document contains a numeric ID; loading assigns session identities in document order.
| Object | Unique within |
|---|---|
| Top-level declarations | their document |
| Fixtures and groups | their layout |
| Fixture shapes | their fixture definition |
| Ports | their controller |
| Controls | their input device |
Layers; graph nodes and root together; clips; mark collections | their sequence |
Layers; graph nodes and root together; clips; live mark collections | their console |
An edge leaving a layer names it layers.layer and the root node is named
root, so a layer and a graph node may share a name. The GUI derives names from what
it creates (pulse, pulse_2, afterglow), and a name typed in the GUI is
converted to snake_case (Glow Trail becomes glow_trail).
References are dotted paths resolved from where they are written:
- a bare name resolves in the enclosing scope: a declaration of the same document, a layer, clip, node or mark collection of the same sequence, or a layer, node, clip or live mark collection of the same console;
layers.layerin an edge'sfrom:reaches a layer's graph node;alias.namereaches a top-level declaration of an imported document;layout.fixturereaches a fixture or group of a layout, whatever groups list it, so changing group membership changes no reference;device.controlreaches a button or axis of an input device;- an owned object is reached through its owner and the owning fields:
show.setup.layout,show.setup.controllers.main,show.setup.layout.desk,show.setup.input_devices.pad.hit.
The expected kind comes from the schema, so a reference to the wrong kind of object is an error at the reference.
Owned and shared objects
Some fields take either a reference or the object written in place, which its
owner then owns: a project's setup, sequences and consoles, a setup's
layout, patch, controllers and input_devices, and a fixture's
definition. Owned and shared
objects behave differently, so the two forms are two meanings, not two
spellings: an owned object is copied and deleted with its owner, and a shared one
is edited once for every user. An owned single value is a record
(setup: Setup { ... }); an owned collection member carries its name
(controllers: [Controller main { ... }]). Effect and operator code is always a
named script declaration. Parameter values, clips, layers and groups are always
owned.
The editor's ownership actions move values between the two forms:
- Move to file promotes an owned value to a declaration, in a new document or this one, and rebases references to its descendants.
- Copy inside parent copies a shared value into its owner, leaving the declaration unchanged.
- Use another links a field to a declaration.
Linked curves and gradients follow their declaration; making one independent keeps its current value in the parameter. New sequences, fixtures, consoles, controllers and input devices are declarations in a new document of their own by default; creation dialogs offer this document, or storing the value inside its owner, under Advanced settings. Routing follows these changes: making a layout or controller independent also makes its patch independent when routes must change, and for the active setup, sequences that target a copied layout become independent before their targets change. Imports follow typed references, and undo and redo include document registration and imports.
Imports
import effects from <effects/standard.donder>, <effects/impact-burst.donder>;
import layouts from <layouts/outputs.data.donder>;
- An import binds an alias to the top-level declarations of one or more documents, which must not repeat names. Paths are relative to the project root and cannot leave it.
- Aliases follow the rule for object names:
snake_caseand not a keyword. A document imports each target once. - An import exposes its documents' own declarations, not what those documents import. Each document declares the imports it uses.
- Mutual imports are valid: the loader indexes a document's declarations before following its imports.
- Scripts import nothing; their functions are document-local.
- When the GUI references an object in another document, it reuses an import or
adds one with a deterministic alias such as
effectsoreffects_2. - The project is the documents reachable by imports from
project.data.donder; a file in the folder is not part of it until something imports it. Each*.donderfile nothing reaches gets a warning, with a fix that imports it from the root. The fix extends the root import named for what the document declares (effects,operators,scriptsfor both,layouts,sequences,consoles,devices, ...), or the firstalias_2,alias_3, ... without a name clash. It also adds a document's sequences and consoles to the project'ssequencesandconsoles. A setup has no fix, because the project names exactly one.
Prepared playback never sees paths, aliases or names.
Schema
Each record lists its fields in order. Option<T> is a T or none; [T] is
a list.
Project
import setups from <setups/main.data.donder>;
import sequences from <sequences/empty.data.donder>, <sequences/layer_test.data.donder>;
import consoles from <consoles/jam.data.donder>;
Project starter {
format: 2,
description: none,
setup: setups.main,
sequences: [sequences.empty, sequences.layer_test],
consoles: [consoles.jam],
}
| Field | Type |
|---|---|
format | integer, the current format marker |
description | Option<string> |
setup | a Setup reference or Setup { ... } |
sequences | [Sequence reference or Sequence name { ... }] |
consoles | [Console reference or Console name { ... }] |
The root document project.data.donder holds exactly one Project, which no
other document may declare. Its format marks the current
project format, PROJECT_FORMAT_VERSION in donder-project-io: any change to
any document format bumps it. The loader reads it before decoding anything else
and refuses a project in another format; there are no migrations. The root document cannot be moved, renamed or
deleted, and there is no other manifest, lockfile or asset inventory.
New projects start as a single project.data.donder with an owned setup, an
empty layout and patch, no controllers or input devices, one owned sequence
and no consoles. The root document imports the
bundled standard effect and operator libraries, so the initial sequence can use
them; other sequence documents need their own imports.
Setup and controllers
Setup main {
description: none,
layout: layouts.outputs_layout,
patch: patches.outputs,
controllers: [output_controller],
input_devices: [devices.keyboard],
}
Controller output_controller {
description: none,
protocol: E131 {
sender_name: "Donder Thirty Output Controller",
bind_address: "0.0.0.0",
priority: 100,
mode: Unicast { destination: "192.168.7.2" },
start_universe: 1,
universes: 30,
channels: 339,
},
}
Controller dig_quad {
description: none,
protocol: Donder {
device: "b0cbd8030790",
ports: [Port { name: port_1, output: 1, slots: 450 }],
},
}
Setup:description,layout,patch,controllers: [controller],input_devices: [input device].Controller:description,protocol.protocolis one of:E131 { sender_name, bind_address, priority, mode, start_universe, universes, channels }withmodeeitherMulticastorUnicast { destination };ArtNet { bind_address, destination, mode, start_universe, universes, channels }with socket addresses such as"0.0.0.0:6454",modeeitherUnicastorBroadcast, andstart_universethe 15-bit port-address of the first universe;Donder { device, ports: [Port] },devicethe controller's twelve lowercase hexadecimal digits.
- An E1.31 or Art-Net controller sends
universesconsecutive universes fromstart_universe, each ofchannelschannels (at most 512; 510 carries 170 RGB pixels). Its channels are numbered across all of them: with 510 channels per universe, channel 510 from 0 is the first channel of the second universe. A route, and one pixel, may run on from one universe into the next. Port:name,output(the Donder controller's physical output, from 1) andslots.
Input devices
InputDevice keyboard {
description: "The computer keyboard, for playing the jam console.",
driver: Keyboard,
controls: [
Button { name: kick, description: none, input: Key { code: KeyA } },
Button { name: swell, description: none, input: Key { code: KeyS } },
Button { name: boost, description: none, input: Key { code: KeyD } },
Button { name: tap, description: "Tap along to the beat.", input: Key { code: Space } },
],
}
InputDevice:description,driver,controls. The setup lists the input devices its consoles play from.driverisKeyboard, the computer keyboard;Midi { port }, the MIDI input ports whose name containsport, ignoring case, or every port when it isnone; orOsc { port }, OSC messages sent over UDP toport, from 1 to 65535, on every network interface. No two OSC devices of a setup share a port.- A control is
Button { name, description, input }, pressed or released, orAxis { name, description, input }, a position from 0 to 1. - A keyboard button's
inputisKey { code }.codeis a key by its browserKeyboardEvent.codename:KeyAtoKeyZ,Digit0toDigit9,F1toF12,Space,Enter,Tab,Escape,Backspace,ArrowUp,ArrowDown,ArrowLeft,ArrowRight,ShiftLeft,ShiftRight,ControlLeft,ControlRight,AltLeft,AltRight,Minus,Equal,BracketLeft,BracketRight,Backslash,Semicolon,Quote,Comma,Period,Slash,Backquote,Numpad0toNumpad9,NumpadAdd,NumpadSubtract,NumpadMultiply,NumpadDivide,NumpadDecimal,NumpadEnter,Insert,Delete,Home,End,PageUp,PageDownandCapsLock.donder_model::KeyCodeis the one list of key names; the schema reads it. - A MIDI button's
inputisNotes { low, high, channel }, note numbers from 0 to 127 withlowat mosthigh, each note its own press held from note on to note off (one note whenlowishigh), orControlChange { number, channel }, from 0 to 119, held at 64 and above. A MIDI axis'sinputisControlChange { number, channel }orPitchBend { channel }.channelis the MIDI channel the input reads, from 1 to 16, ornonefor every channel. - An OSC button's
inputisAddress { path }, pressed by a first argument above 0, released by 0, and pressed and released at once by a message with no arguments. An OSC axis'sinputisAddress { path, low, high }, its first argument running fromlowtohigh, two finite floats withlow < high.pathis a/and then printable characters other than spaces and*?[]{}#,, matched exactly. - Control names are unique within their device, and no two controls read the same input; every note of a button's range is an input it reads. Two MIDI inputs of the same kind conflict when they share a note or number and a channel: when either reads every channel, or both read the same one.
In the GUI, the setup adds and attaches input devices, and an input device opens in its own editor.
Layouts and fixtures
Layout outputs_layout {
description: none,
root: [all_outputs],
items: [
Group { name: all_outputs, description: none, members: [output_01] },
Fixture {
name: output_01,
description: none,
definition: fixtures.vertical_113,
transform: Transform {
position: (0m, 0m, 0m),
rotation: (0.0, 0.0, 0.0),
scale: (1.0, 1.0, 1.0),
},
},
],
}
FixtureDefinition vertical_113 {
description: none,
shapes: [
Shape {
name: vertical_strip,
diameter: 0.05m,
reverse: false,
transform: Transform {
position: (0m, 0m, 0m),
rotation: (0.0, 0.0, 90.0),
scale: (1.0, 1.0, 1.0),
},
geometry: Line { length: 11.2, count: 113 },
},
],
}
Layout:description,root,items.itemslists every fixture and group once, eachGroup { name, description, members }orFixture { name, description, definition, transform }, wheredefinitionis aFixtureDefinitionreference orFixtureDefinition { ... }owned by that fixture. Fixture order initemsis placement order.rootand a group'smembersname items of the layout in display order. An item may be a member of several groups, and of the root as well. Each list names an item once, a group cannot contain itself through its members, and every item is inrootor some group.- A group targets its fixtures depth-first in member order; a fixture reached more than once keeps its first position.
Transform:position, an(x, y, z)tuple of distances within 2 km of the origin;rotationin degrees andscale, each a tuple of floats.FixtureDefinition:description,shapes: [Shape].Shape:name,diameter(a distance from 1µm to 100m),reverse,transform,geometry, which is one of:PixelLine { length, count }Polyline { points: [(x, y, z) distances], count }Arc { radius, start_degrees, sweep_degrees, count, closed }Grid { columns, rows, width, height, axis, corner, serpentine }withaxiseitherRowsorColumnsandcornerone ofBottomLeft,BottomRight,TopLeftorTopRight
Lengths inside geometry (length, radius, width, height) are floats in
meters. Fixture rules are in fixture authoring.
Patches
Patch outputs {
description: none,
routes: [
Route {
target: layouts.outputs_layout.output_01,
pixels: none,
controller: setups.output_controller,
port: none,
start_channel: 0,
encoding: Rgb { order: (1, 0, 2) },
gamma: 1.0,
brightness: 1.0,
dither: false,
},
],
}
Route:target(a fixture; groups are not routed),pixels,controller,port,start_channel,encoding,gamma,brightness,dither.- On an E1.31 or Art-Net controller
portisnoneandstart_channel, from 0, counts across all its universes. On a Donder controllerportnames one of its ports andstart_channel, from 0, counts in that port. dither: truevaries each byte over an eight-frame cycle so it averages to the exact level, keeping dim colors' hue. It suits outputs that receive every frame at a high rate; at a long FSEQ step the cycle shows as flicker.pixelsisPixelSpan { start, count }, ornoneto route the whole target, including later pixel-count edits.encodingisRgb { order: (a, b, c) }orRgbw { order: (a, b, c, d) }: the color each of a pixel's channels carries, in channel order, with 0 red, 1 green, 2 blue and 3 white.(1, 0, 2)is GRB, the order of WS2811 and WS2812 pixels.
Sequences
Sequence layer_test {
description: none,
duration: 249.753832s,
frame_rate: 144,
audio: none,
marks: [
MarkCollection { name: wipe_marks, description: none, color: #45b7ff, times: [4s, 5s, 6s, 7s] },
],
layers: [
Layer { name: default, description: none, color: #38bdf8, enabled: true },
Layer { name: glow, description: none, color: #e0414f, enabled: true },
],
clips: [
Clip {
name: pulse,
description: none,
layer: default,
start: 58.971401s,
duration: 1s,
target: elements.outputs_layout.all_outputs,
scope: WholeTarget,
effect: effects.Pulse,
params: { gradient: gradients.ember_core_gradient, pulse_shape: Curve { points: [(0.0, 1.0), (1.0, 0.0)] } },
},
],
graph: Graph {
nodes: [
LayerNode { layer: default, position: (566.45416, -474.141) },
RootNode { position: (1393.0885, -375.6623) },
LayerNode { layer: glow, position: (444.03857, -40.094635) },
OperatorNode {
name: afterglow,
operator: operators.Afterglow,
params: {},
position: (815.0807, -62.519207),
},
],
edges: [
Edge { from: layers.default, to: root },
Edge { from: layers.glow, to: afterglow.input },
Edge { from: afterglow, to: root },
],
},
automation: [
AutomationClip {
row: elements.outputs_layout.all_outputs,
start: 0s,
duration: 249.753832s,
curve: Curve { points: [(0.0, 0.505), (0.103248, 0.787)] },
bindings: [
Bound { binding: NodeParam { node: afterglow, param: seconds }, window: (0.0, 1.0) },
],
detached: [],
},
],
}
-
Sequence:description,duration,frame_rate,audio(a path ornone),marks,layers,clips,graph,automation. -
MarkCollection:name,description,color,times, in time order. A mark is its time,4s, or its time and a one-line label,(4s, "chorus"), for lyric lines, singers or section names; the editor shows and edits labels on the timeline. -
Layer:name,description,color,enabled. The first layer is the default layer, which new clips use and which cannot be deleted. -
Clip:name,description,layer,start,duration,target(a fixture or group),scope(PerFixtureorWholeTarget),effect,params. -
Parameters are overrides. A parameter absent from
paramsfollows the definition's declared default, including when that default changes later; a parameter present keeps its value, even if it equals the default. Values are typed by the definition and written in its parameter order: ints, floats, bools, colors, enum options (Forward, or with every one of its fields in order,FixedTime { revolution_time_ms: 250.0 }), mark collections by name, curves and gradients by reference or as literals, and arrays as lists. A literal is a declaration's fields without itsdescriptionand name, in the same form:Curve { points: [(position, value), ...] }andGradient { space: LinearRgb, stops: [(position, #color), ...] }. A marks value may benone: no collection, so the effect sees no marks. New effects and operators start withnone, and deleting a collection sets the values that named it tonone. -
Graph:nodesandedges. A node is one of:LayerNode { layer, position }, named by its layer, which appears in at most one node;OperatorNode { name, operator, params, position };RootNode { position }, namedroot, exactly one.
Every node has one output, so an edge names only the input it reaches:
to: afterglow.inputnames an operator input andto: rootthe root node.positionis the node's place on the graph canvas. -
AutomationClip:row(the fixture or group whose automation row holds it),start,duration,curve,bindingsanddetached. A target isClipParam { clip, param }orNodeParam { node, param }; a binding isBound { binding, window }and a detached binding isDetached { binding }. Deleting a bound clip or node removes its bindings; a clip may be bound to nothing.
Every place a 0..1 value reaches a parameter (an automation binding, a
console's Set and a console's PlayedValue) has a window: (low, high), the
part of 0..1 the binding uses: the value v becomes low + (high - low) * v
before it maps onto the parameter's range. (0.0, 1.0) is the whole range,
(0.0, 0.7) stops at 70% of it and (1.0, 0.0) inverts it. Both ends lie in
0..1. The window belongs to the binding, so one clip bound to two parameters
has a window for each, and a detached binding keeps none.
Layers produce signals, operators combine and transform them, and the single root node is what plays. Nodes not connected to the root are kept but not prepared. An input with no edge, the root's included, is black. Any input may have several edges: they combine by their channel-wise maximum, as the clips of a layer do.
Every fixture or group has one clip row and one automation row. A member of
several groups shows its rows under each, and every copy holds the same clips.
An automation clip's row is only placement: moving it between rows does not
change its bindings. One clip can bind several parameters. The curve's 0..1
value, through the binding's window, maps onto each parameter's declared range (a curve parameter's point
values), an enum's options in order, or a bool (on at 0.5). Several clips may
bind the same parameter if they do not overlap in time; preparation merges them
into one envelope. Before the first clip the parameter holds that clip's first
value, and in a gap it holds the value the previous clip ended on, so splitting
a clip leaves playback unchanged. When the GUI deletes a bound clip or operator, or
replaces its definition so a parameter no longer fits, the binding moves to
detached, so it can be reattached rather than silently lost.
In the editor:
- Copy and cut put the selection on the system clipboard as a data document:
one
Sequence clipboard, the copied sequence with only the selected clips, automation clips or marks, and the imports its references need. Paste reads that document against the open project, so any text in this format pastes, and other text is refused. - Copy and paste of clips and automation together keeps relative timing and target offsets, names pasted clips afresh, places each clip on the layer of its layer's name, and remaps bindings to the copies. Bindings to clips outside the copied selection are dropped, and a binding to an operator node is kept when the sequence pasted into has the node and no overlapping automation clip binds it; a lone automation clip pastes without clip bindings. Marks paste into the collections of their names.
- A paste that does not fit is rejected as a whole. Moving, resizing, cutting or pasting a selection is one history entry.
- Resizing an automation clip crops it: the edge moves over fixed content, points outside the new window are dropped, and a cut edge gains a point at the value it cut through. Holding Ctrl while resizing stretches the curve instead. Splitting crops the clip into two clips with the same bindings.
- The slice tool (C, or the scissors button) cuts effect clips: clicking cuts
the clip under the line, and dragging vertically cuts every clip the line
crosses, in one history entry. The right half is a fresh clip whose
timeandprogressstart again at zero; it gains the same automation bindings as the left half, so automation continues across the cut. Alt snaps the line to marks, and Escape returns to selecting. - Curve points keep their authored order and edit as in FL Studio's automation clips, minus tension (segments are straight). Clicking anywhere in a clip below its header adds a point there and drags it; the header moves the clip. A point wins over the clip edge it sits on. Right-clicking a point removes it, and a right-drag removes every point it sweeps over (a curve keeps one). A dragged point stays between its neighbors, so a step (two points at one time) never reorders. Shift aligns the dragged point's time or value with a neighbor; Alt snaps clip edges and point times to visible marks. Committing a curve drops points that cannot affect sampling.
- In the graph, operator names, parameters and automation controls live inside each node, and layer controls inside layer nodes. Right-click to add or delete; deleting a layer asks where its clips should move. The default layer and the output cannot be deleted.
- Row heights, node sizes, graph pan and zoom and guides are workspace preferences, not project data, and are outside undo history.
Consoles
A console is played live from input devices instead of on the timeline; it
never plays on top of a sequence. Each action edits it at the time of the event
that runs it: Play and Start..Stop place clips, Mark adds a mark and
Set writes a parameter's value. See Live input for how a
console plays.
Console jam {
description: "Play the outputs live from the keyboard.",
frame_rate: 100,
marks: [LiveMarks { name: beat, description: none, color: #22c55e }],
layers: [Layer { name: default, description: none, color: #38bdf8, enabled: true }],
clips: [
ConsoleClip {
name: background,
description: "Pulses on every tapped beat.",
layer: default,
target: elements.outputs_layout.all_outputs,
scope: WholeTarget,
effect: effects.MarkPulse,
params: {
beats: beat,
accent: gradients.cool_gradient,
pulse_shape: curves.ease_down,
decay_seconds: 0.01,
},
played: [],
},
ConsoleClip {
name: flash,
description: none,
layer: default,
target: elements.outputs_layout.all_outputs,
scope: WholeTarget,
effect: effects.Pulse,
params: { gradient: gradients.white_strobe_gradient, pulse_shape: curves.ease_down },
played: [],
},
ConsoleClip {
name: wash,
description: none,
layer: default,
target: elements.outputs_layout.all_outputs,
scope: WholeTarget,
effect: effects.Pulse,
params: { gradient: gradients.aurora_gradient, pulse_shape: curves.center_peak },
played: [],
},
],
always: [Always { clip: background, length: 4s }],
events: [
On {
event: Press { control: devices.keyboard.kick },
actions: [Play { clip: flash, copies: 4, length: Fixed { duration: 0.4s } }],
},
On {
event: Press { control: devices.keyboard.swell },
actions: [Start { clip: wash, length: 4s }],
},
On { event: Release { control: devices.keyboard.swell }, actions: [Stop { clip: wash }] },
On { event: Press { control: devices.keyboard.tap }, actions: [Mark { into: beat }] },
On {
event: Press { control: devices.keyboard.boost },
actions: [
Set { param: ClipParam { clip: background, param: decay_seconds }, window: (0.0, 1.0) },
],
},
On {
event: Release { control: devices.keyboard.boost },
actions: [
Set { param: ClipParam { clip: background, param: decay_seconds }, window: (0.0, 1.0) },
],
},
],
graph: Graph {
nodes: [
LayerNode { layer: default, position: (80.0, 120.0) },
RootNode { position: (420.0, 120.0) },
],
edges: [Edge { from: layers.default, to: root }],
},
}
-
Console:description,frame_rate,marks,layers,clips,always,events,graph. -
LiveMarks:name,description,color. A live mark collection starts empty each session and gains a mark each time aMarkaction runs. -
layersandgraphare exactly a sequence'sLayerandGraph, with the same rules: the first layer is the default, a layer is in at most one layer node, there is one output node, and operator inputs on the output path are connected. -
ConsoleClip:name,description,layer,target,scope,effect,params,played: a clip withoutstartorduration. Parameters are a clip's, except that a marks value names one of the console's live mark collections, or isnone.playedarePlayedValue { param, from, window }: each copy takes that parameter from the press that started it,fromVelocityorPitchClass, throughwindow, mapped onto the parameter's range as automation is. -
alwaysareAlways { clip, length }: clips that play from the session's start, each starting again from its beginning everylength. -
On:event,actions.eventisPress { control }orRelease { control }of a button, orMove { control }of an axis, eachdevice.control.actionsrun in order, and are each one of:Play { clip, copies, length }plays a copy ofclipon top of those playing, up tocopies(1 to 16) at once, reusing the oldest.lengthisFixed { duration }orScaled { by, shortest, longest },bybeingVelocityorAxis { control }(adevice.controlaxis; one not yet moved reads 0), a value from 0 to 1 read when the copy starts and mapped fromshortesttolongest.Start { clip, length }plays one copy until stopped, starting it again from its beginning everylength; it does nothing while the clip plays.Stop { clip }stops every copy of the clip.Toggle { clip, length }isStartwhile no copy plays, elseStop.
A copy's effect sees its length as its
duration; a held copy'stimeandprogressstart again at zero with each pass.Mark { into }adds a mark to that live mark collection.Set { param, window }writes the event's value into a parameter: an axis's position, a press's velocity, or 0 for a release.paramisClipParam { clip, param }, an automatable parameter of a console clip, set on every copy of the clip, orNodeParam { node, param }, an automatable parameter of an operator node of the console's graph. The value, throughwindow, maps onto the parameter exactly as an automation curve does, and the parameter rests at the window's low end until the firstSet. One control sets a parameter, by any of its events. Deleting a clip or node removes theSets of its parameters.
-
Every input device a console of the project reads must be among the project setup's
input_devices, and its clips target the setup's layout.
In the GUI, the project lists its consoles with a Perform button each, the setup lists its input devices, and each input device and console has its own editor; a console's layers and graph use the sequence graph editor.
Curves and gradients
Curve ease_down {
description: none,
points: [(0.0, 1.0), (0.5, 0.2), (1.0, 0.0)],
}
Gradient warm_gradient {
description: none,
space: LinearRgb,
stops: [(0.0, #fff4d6), (0.35, #ffb000), (1.0, #ff2a00)],
}
A gradient's space is how it interpolates between stops; the stops themselves
are the same colors in every space:
LinearRgblerps the red, green and blue channels.Hsvlerps hue, saturation and value, with hue along the shorter arc. A gray stop takes its hue from the nearest stop that has one, and a black stop its hue and saturation, so a fade to black stays one hue.Oklablerps Oklab's lightness and opponent axes, treating the channels as linear light, so mixes keep an even lightness instead of dipping through muddy midpoints.
The preparation step stores each stop's color in the space's own coordinates (for Oklab, cube-rooted LMS), so playback lerps and then decodes once per sample.
Descriptions
The project, setups, controllers, input devices and their controls, layouts, fixtures
and groups, fixture definitions, patches, sequences, layers, mark collections,
clips, consoles, live mark collections, console clips, curves
and gradients have a description. The GUI edits an open object's description in
the bar above its editor, and an item's with the item: a layout item's in its
name dialog, a clip's in the clip inspector, a layer's in its graph node, and a
mark collection's in the marks inspector. Text is trimmed, and empty text is
none.
Scripts
Scripts are the effect language, with these rules shared with data:
-
Enum options are
PascalCase:param direction: enum { Forward, Backward } = Forward;, compared asdirection == Forward. Asnake_caseoption is an error with a fix. A parameter's options may carry fields,Speed { speed: float in 0.0..100.0 = 60.0 }, which amatcharm binds; see options with fields. -
Effects, operators, parameters and functions may carry a description string after their name, or for a parameter after its default. The inspector shows effect and parameter descriptions.
effect Pulse "A gradient that swells and fades over the clip." { param colors: gradient "Colors across the target."; param speed: float in 0.0..4.0 = 1.0 "Pulses per second."; sample { colors[pixel.fraction] * sin(time * speed * TAU) } } fn glow "Brightness of a soft dot." (position: float, head: float) -> float { ... } -
Scripts accept non-canonical numbers and int-to-float widening, since the GUI never reprints them.
Validity
donder_model::validate_sequence and donder_model::validate_console are the
single sequence and console validators, and they share the layer and graph rules.
Project loading and checked GUI edits run them before accepting state;
preparation does not repeat them.
- Duration is positive. Frame rate is positive, and duration × frame rate is at most 250,000 frames. All times fit the portable 32-bit microsecond clock, and positive durations cannot round to zero.
- Names are
snake_caseand unique where the table above says. Timed objects fit within the sequence. - Clips reference an existing layer, a compatible target and a defined effect, and supply every parameter that has no default and no unknown ones, each within its declared range. Reduction bounds that depend on an array or marks length must fit the 10,000-iteration limit with the supplied values.
- The graph has one output, typed acyclic connections, and layer nodes that reference distinct layers. Operator definitions, parameters and port types are checked even on disconnected branches.
- Active automation bindings target existing parameters that support automation. A clip binds a target at most once (active or detached), and clips that bind the same target do not overlap. Automation curve values and every binding window's ends lie in 0..1.
- A console's frame rate is positive and at most 1,000. Its clips follow the
clip rules without timing and all target one layout, and
alwaysnames each clip at most once. A clip is played either byPlayactions or byStart,Toggleandalways, not both. Actions name existing clips and live mark collections;Setnames an automatable parameter of a console clip or operator node, which one control sets and no played value also sets;copiesis 1 to 16; lengths,always's too, are positive, fit the playback clock and haveshortestat mostlongest, and a length scaled by an axis names an axis. - Events read controls of input devices in the project's setup:
PressandReleasea button, andMovean axis, which runs onlySet. A clip's played values name automatable parameters of its effect, each at most once, that noSetwrites; onlyPressevents start the clip and it is not inalways, andPitchClassneeds every control that starts it to read notes.
Saving
Saving prints every project-owned data document from typed state with the
canonical printer: two-space indent; a record, list or map stays on one line
when it fits in 100 columns and otherwise puts each item on its own line; long
lists of numbers and tuples (curves, mark times) wrap densely. Because tokens
are canonical and every field is explicit, saving a loaded project rewrites no
byte of a canonically formatted document, and changes only whitespace in any
other valid one. Script text is kept exactly and never regenerated. Audio is a
project-relative path; copying a sequence keeps the path and does not copy audio
bytes. Create Standalone Project Copy (and donder copy) writes a separate
project containing the loaded sources and referenced audio.
Each file is written through donder_project_io::atomic_write, which replaces
it with a complete synced temporary file. That keeps any one file from being
truncated, but a multi-file save is not a crash-atomic transaction. Saving
refuses, before writing anything, a typed object with no source document, a
missing source object, or a cross-document reference with no import; it never
invents an alias or flattens a definition. All declarations in loaded documents
are typed, including unused ones. Unreferenced files are left alone.
crates/donder-project-io/tests/project_io/exact_round_trip.rs, roundtrip.rs
and path_refactor.rs cover byte-exact save after load, whitespace
normalization, typed edits with save and reload, list order, ownership, imports,
assets, retained script text, refusal of inconsistent saves, and import-path
moves. schema_strictness.rs and diagnostics.rs cover unknown and misplaced
fields, value types, references and diagnostic ranges.
Implementation
donder_language::dataholds the syntax tree, the error-tolerant parser, the canonical printer and literal rules, and the schema traits (Data,Record,OwnedRecord,OwnedNamedRecord,Reference,Name,Params,Meters,Path).donder_project_io::documentdeclares the document types, decodes declarations and encodes typed state;loaderresolves declarations into the typed project. Domain validation stays with the domain types, which both loading and the GUI's edits call, so the text and the GUI accept exactly the same states.donder-language-serverprovides editor features for both document kinds; see Text editing.