Docs / Format mappings / pd
Pure Data
A Pure Data patch, and a Max patch, are encodings. A host is Rig when it emits entities with POD components keyed by schema ids it supports (honors). There is no rig.pd.* layer and no rig.max.* layer. Portable meaning is the node graph, plus rig.music.* and rig.audio.* when the patch is about time or sound. A subtractive voice inside the patch is rig.synth.* - music.md. Product names stay out of schema ids (same rule as rig.music.clock). Patcher-only fields travel as x.pd.* or x.max.*.
.pd and .maxpat stay the source files. The Contract does not inline either language.
Map
| Patch | Rig |
|---|---|
| Object box | rig.node.node. typeId is the host catalog key. title may carry the box text. Creation arguments are rig.node.param |
| Inlet / outlet | rig.node.pin. kind is in or out. type is a property datatype (float, vec2, ...), which is the value, not the rate |
| Cord | rig.node.link |
| Signal cord and message cord | The same link. The rate belongs to the catalog entry for typeId (in Pure Data the tilde is part of the object). Do not add a rate field on the pin |
| Bang | A message with no stored payload. The firing stays in the host, with the other live cord values |
| send / receive, throw~ / catch~ | rig.node.bus |
| Subpatch | A node with nested, and rig.node.publish for the inlets that show on the outside |
| Abstraction file | rig.media.asset_ref the host loads |
| Box on the canvas | position on the node. It travels. It is not a world transform |
| Selection, cord readouts | Host state |
| metro, tempo, transport | rig.music.transport and rig.music.clock. One bpm. Do not keep a second tempo in a node param |
| notein / noteout / ctlin | rig.music.midi_input / midi_output are endpoints. Authored notes are rig.music.note. The queue this instant stays in the host |
| dac~ / adc~ | A node the host binds to rig.audio.voice, rig.audio.bus, or capture. The device is not a schema |
| osc~ | rig.synth.oscillator when it is the tone. The Hz argument stays on the node. An LFO stays rig.mod.lfo. A box that is only a patcher object keeps a catalog typeId |
| lop~ / hip~ / bp~ / vcf~ | rig.synth.filter. The cutoff argument stays on the node |
| *~ | rig.synth.amplifier when that multiply is the level stage. The right-hand argument stays on the node |
| line~ / vline~ | The ramps a patch uses to open a level. Four times written as a voice stay rig.synth.envelope |
How a player names a key or a chord is music.md. That page is the part. This page is the patch.
Round trip
A .pd file makes the trip a KiCad board makes. The text stays the source. The document a host loads is the graph.
- Import
voice.pdto a.rigz. The original file sits atdata/voice.pd. The graph entity carries arig.media.asset_ref(kinddocument) whosepathisvoice.pd. - The patch is one
rig.node.graph. Each#X obj,#X msg, atom, and comment is a node, in file order.typeIdis the first token (osc~,*~,lop~).titleis the box text from that token through the arguments (osc~ 65.41).positionis the box x y. Nodeidis that canvas index, the number#X connectwrites, counting every box on the canvas. A nested canvas is a node withnested, and its indices start again at 0. - Pin
idis unique on that node. Pinnameis the inlet or outlet number ("0","1").kindsays which. A link stores those pin ids.#X connect a b c dis nodeaoutletbto nodecinletd. - Edit in any Rig host. Move a box, change
title, rewire a cord, add a node. - Export by merging onto
voice.pd:- A node whose id is still a canvas index rewrites that box's position and
title. Colors, fonts, labels, and the other tokens on a GUI box stay as they were. - An index with no node was deleted. Drop that box.
- A node whose id is not an index yet is new. Append it.
- Write
#X connectfrom the links. After a deletion the file's indices are dense again. The document keeps its node ids. The writer maps id to the emitted index. #N canvassize and font, arrays, and graph-on-parent stay in the source file.
- A node whose id is still a canvas index rewrites that box's position and
Without the original file, a writer still emits a valid .pd from the graph. Canvas size, font, and GUI chrome use Pure Data's defaults.
A voice authored as rig.synth.* loads without a patch (examples/synth-voice.json). A writer can print a fresh .pd from those blocks: osc~, lop~ or vcf~, *~, and line~ for the ramps. The writer prints Hz on the box, converted from the oscillator's MIDI pitch. The document keeps the MIDI number.
A worked patch, cosine into a low-pass into a level into dac~: examples/pd-voice.json.
Max is the same graph. A .maxpat writer merges onto that JSON, matching the box id the file already stores.
Other graphs
Do not merge these into rig.node.*. See Grouping graphs.
| Idea | Rig |
|---|---|
| Eurorack / EuroSynth jack | rig.modular.port - eurosynth.md |
| Subtractive voice | rig.synth.oscillator, filter, amplifier, envelope - music.md |
| ROS 2 node | A named entity. Not a patcher node - ros.md |
| Circuit terminal | rig.circuit.pin |
A worked graph, two boxes and one cord: examples/node-graph.json. A worked .pd voice: examples/pd-voice.json.