From 36b8c613ee397d08168c323bcb2c383772b73a64 Mon Sep 17 00:00:00 2001 From: Hans-Christoph Steiner Date: Wed, 20 Sep 2006 03:08:58 +0000 Subject: added HTML file from puredata.org since the creators don't seem to be maintaining this svn path=/trunk/; revision=5975 --- doc/additional/pd-fileformat.html | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 doc/additional/pd-fileformat.html (limited to 'doc') diff --git a/doc/additional/pd-fileformat.html b/doc/additional/pd-fileformat.html new file mode 100644 index 00000000..b132fd30 --- /dev/null +++ b/doc/additional/pd-fileformat.html @@ -0,0 +1,22 @@ + + + + + +Unofficial PD v0.37 fileformat specification +

Unofficial PD v0.37 fileformat specification
by Simon Asselbergs and Tjeerd Sietsma
Hogeschool voor de Kunsten Utrecht
Faculty of Art Media and Technology
October 23rd 2004

+ Copyright (c) 2005 Free Software Foundation. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is online at + http://www.gnu.org/licenses/fdl.html. + Initial authors: Simon Asselbergs and Tjeerd Sietsma. +

introduction | records | wiring | elements and objects | common parameters | reference | EBNF version

Introduction

This file describes the fileformat of patchfiles (*.pd) of Miller Puckette's PureData.

It is released because:

This documents is currently unofficial, beware that there is no warranty whatsoever.
If you find this document incorrect or incomplete please send us an e-mail using the links at the top of this document.
There are a few things still unknown, we don't exclude the possibility those things are used for compatibility with Max.

back to top


Records

The PD fileformat is a genuine custom textfile format, not to be confused with XML.
It consists of one ore more records.
Each record may cover multiply lines but they all have thesame syntax:

#[data];\r\n

where[data] holds the record data, \r represents an ASCII code 13 carriage return character, and \n represents an ASCII code 10 line-feed character.
Let us take a closer look on the records contents.

Each record consists of a chunk type, element type and optional parameters like this:

#[chunk_type] [element_type] [p1] [p2] [p3] [...];\r\n

[chunk_type] is a sinlge character with only three possible values: "X" for an object, "N" for a new window, and finally "A" for array data.

[element_type] is a predefined PD element. This declaration is also used for wires. Object elements are numbered in order of appearance in the file, all other elements are excluded from numbering. These numbers are pure virtual and can not be seen directly in the file.

[p1] [p2] [p3] [...] are the required parameters for each element, this differences per element.

back to top


Wiring

Almost all objects can be interconnected with wires in PureData. Each wire is stored in the file using the following syntax:

#X connect [source] [outlet_number] [sink] [inlet_number];\r\n

[source] Is the number of the object the data is coming from. [outlet-number] Represents the number of the outlet of the source object where the wire starts. Sequentially, [sink] is the number of the target object, and finally [inlet_number] specifies inlet of the target object to which the wired is connected.
Logically, the objects (again, connects excluded) are numbered from 0 to the total number of objects in the file using the integer format. The inlets and outlets are numbered likewise.
Please keep this in mind, to prevent making often made off-by-one errors.

back to top


Elements and objects

There's a difference between elements and objects. Elements are the parts that together make up the entire layout of a patch, including windowsizes and position. Objects are the building blocks of PureData that contain functionality, gui-related or not.

All other elements are used to build actual PureData objects:

back to top


Common parameters

back to top


Reference

back to top



A
Description:
 Announces array data
Syntax:
 #A [p1] [p2] [p3] [...];\r\n
Parameters:
 [p1] [p2] [p3] [...] floating point variables representing array elements
Example:
 See Array
Remarks:
 Used only in combination of an array definition

back to reference index

 

N
Description:
 Announces a frameset
Syntax:
 #N [new_frame];\r\n
Parameters:
 [new_frame] new frameset, currently only a new patchwindow can be defined
Example:
 see canvas
Remarks:
 Currently used only for new canvas definitions

back to reference index

 

canvas
Description:
 Defines window properties
Syntax:
 #N canvas [x_pos] [y_pos] [x_size] [y_size] [name] [open_on_load];\r\n
Parameters:
 [x_pos] - horizontal position offset of frameset (window)
[y_pos] - vertical position offset of frameset (window)
[x_size] - horizontal size of frameset (window)
[y_size] - vertical size of frameset (window)
[name] - name / handle of frameset
[open_on_load] - when flag is set the canvas is opened when the patch is loaded
Example:
 #N canvas 0 0 452 302 12;
Example:
 #N canvas 0 0 452 302 thiscanvas 0;
#X restore 41 136 pd thiscanvas;
Remarks:
 In this example patch there are two canvas definitions.
The first example has a special syntax, the attributes [name] and [open_on_load] have been replaced by a [font_size] attribute. This is only the case when the canvas definition is the first record in the patchfile, to define the position and size of the main patcher window, and set the default font size. When a first canvas definition is absent the default values of PureData are used. Note that in this case you can alter the default font size with a command line parameter.
The second example shows a regular internal subpatch definition. Normally a canvas defintion is always postceeded with a restore element to define the position within the canvas, and the name of the subpatch.
Presumably, the canvas name in the canvas defintion and restore definition should be thesame.

back to reference index

 

X
Description:
 Announces regular elements
Syntax:
 #X [element];\r\n
Parameters:
 [element] - element definition
Example:
 #X obj 50 36;
Remarks:
 Used with every element definition except canvas definitions

back to reference index

 

array
Description:
 Array
Syntax:
 #X array [array_name] [array_size] float [save_flag];\r\n
Parameters:
 [array_name] - name / handle of the array
[array_size] - total number of elements of an array
[save_flag] - with this flag set the array data is stored in the patch
Example:
 #N canvas 0 0 450 300 graph4 0;
#X array array3 10 float 1;
#A 0 0 0 0 0 0 0 0 0 0;
#X coords 0 1 99 -1 200 140 1;
#X restore 270 193 graph;
Remarks:
 An array is a gui-form of a table, always visualised using a graph. Optionally the array data can be saved in the patch - which can be very space-consuming and CPU intensive when you want to store a large number of floating point values typed out in a textfile.

back to reference index

 

connect
Description:
 Wires GUI-elements
Syntax:
 #X connect [source] [outlet] [target] [inlet];\r\n
Parameters:
 [source]
[outlet]
[target]
[inlet]
Example:
 #X obj 30 27 midiin;
#X obj 26 59 midiout;
#X connect 0 0 1 0;
#X connect 0 1 1 1;
Remarks:

Objects are virtually numbered in order of appearance in the file, starting from zero. Inlets and outlets of the objects are numbered likewise.

back to reference index

 

coords
Description:
 Visual ranges of a frameset (window)
Syntax:
 #X coords [x_from] [y_to] [x_to] [y_from] [width] [heigth] [graph_on_parent];\r\n
Parameters:
 [x_from] - first index to display
[y_to] - dynamic range of graph upper border
[x_to] - last index to display
[y_from] - dynamic range of graph lower border
[width] - relative horizontal size of graph
[heigth] - relative vertical size of graph
[graph_on_parent] - when set displayes child path, when unset graph is displayed like an object
Example:
 #N canvas 0 0 452 302 graph1 0;
#X coords 0 1 100 -1 200 140 1;
#X restore 58 26 graph;
Remarks:

A coords statement must always be preceded with a canvas statement which also holds the graph name.
A coords statement must always be terminated with a restore statement that has the reserved handle graph
Off limit values will be displayed outside the graph in the PureData GUI.

back to reference index

 

floatatom
Description:
 Defines a number box
Syntax:
 #X floatatom [x_pos] [y_pos] [width] [lower_limit] [upper_limit] [label_pos] [label] [receive] [send];\r\n
Parameters:
 [x_pos] - horizontal position within window
[y_pos] - vertical position within window
[width] - number of digits
[lower_limit] - minimal value
[upper_limit] - maximum value
[label_pos] - label position relative to floatatom position. 0 = left, 1 = right, 2 = top, 3 = bottom
[label] - floatatom label/name
[receive] - receive symbol name
[send] - send symbol name
Example:
 #X floatatom 32 26 5 0 0 0 - - -;
Remarks:

When the value of [upper_limit] minus the value of [lower_limit] is less than one, or the [width] attribute is set to one, PureData resets these values both to zero.
Floatatom and symbolatom are the only elements that uses "-" characters to indicate that no value has been assigned to its attributes [label], [receive] and [send].

back to reference index

 

msg
Description:
 Defines a message
Syntax:
 #X msg [x_pos] [y_pos] [p1] [p2] [p3] [...];\r\n
Parameters:
 [x_pos] - horizontal position within the window
[y_pos] - vertical position within the window
[p1] [p2] [p3] [...] the content of the message
Example:
 #X msg 61 48 read audio.wav;
Remarks:

-

back to reference index

 

obj
Description:
 Defines an object
Syntax:
 #X obj [x_pos] [y_pos] [object_name] [p1] [p2] [p3] [...];\r\n
Parameters:
 [x_pos] - horizontal position within the window
[y_pos] - vertical position within the window
[object_name] - name of the object (optional)
[p1] [p2] [p3] [...] the parameters of the object (optional)
Example:
 #X obj 55 50;
#X obj 132 72 trigger bang float;
Remarks:

The first line is an example of an empty object. The second line describes a trigger object with its parameters.

back to reference index

 

bng
Description:
 Defines a bang
Syntax:
 #X obj [x_pos] [y_pos] bng [size] [hold] [interrupt] [init] [send] [receive] [label] [x_off] [y_off] [font] [fontsize] [bg_color] [fg_color] [label_color] ;\r\n
Parameters:
 [x_pos] - horizontal position within the window
[y_pos] - vertical position within the window
[size] - square size of the gui element
[hold] - hold time in milliseconds, ranges from 50 to 1000000000
[interrupt] - interrupt time in milliseconds, ranges from 10 to 250
[init] - bang on load
[send] - send symbol name
[receive] - receive symbol name
[label] - label
[x_off] - horizontal position of the label text relative to the upperleft corner of the object
[y_off] - vertical position of the label text relative to the upperleft corner of the object
[font] - font type
[fontsize] - font size
[bg_color] - background color
[fg_color] - foreground color
[label_color] - label color
Example:
 #X obj 27 32 bng 15 10000 100 1 empty empty empty 0 -6 0 8 -262144 -1 -1;
Remarks:

Hold time is for how long you see a flash when you click on the bang, interrupt time is for how long you don't see it flash when you click on this object while it's flashing.
[send], [receive] and [label] cannot be named "empty", this is a reserved name for when no value is assigned.

back to reference index

 

tgl
Description:
 Defines a toggle
Syntax:
 #X obj [x_pos] [y_pos] tgl [size] [init] [send] [receive] [label] [x_off] [y_off] [font] [fontsize] [bg_color] [fg_color] [label_color] [init_value] [default_value] ;\r\n
Parameters:
 [x_pos] - horizontal position within the window
[y_pos] - vertical position within the window
[size] - square size of the gui element
[init] - set on load
[send] - send symbol name
[receive] - receive symbol name
[label] - label
[x_off] - horizontal position of the label text relative to the upperleft corner of the object
[y_off] - vertical position of the label text relative to the upperleft corner of the object
[font] - font type
[fontsize] - font size
[bg_color] - background color
[fg_color] - foreground color
[label_color] - label color
[init_value] - value sent when the [init] attribute is set
[default_value] - default value when the [init] attribute is not set
Example:
 #X obj 29 44 tgl 15 1 empty empty empty 0 -6 192 8 -262144 -1 -1 234 234;
Remarks:

[send], [receive] and [label] cannot be named "empty", this is a reserved name for when no value is assigned.
The [default_value] attribute can be changed in a patch and saved, this is why there are different values for [init_value] and [default_value]

back to reference index

 

nbx
Description:
 Defines a Number2 number box
Syntax:
 #X obj [x_pos] [y_pos] nbx [size] [height] [min] [max] [log] [init] [send] [receive] [label] [x_off] [y_off] [font] [fontsize] [bg_color] [fg_color] [label_color] [log_height];\r\n
Parameters:
 [x_pos] - horizontal position within the window
[y_pos] - vertical position within the window
[size] - number of digits the element displays
[height] - vertical size of element in pixels
[min] - minimum value, typically -1e+037
[max] - maximum value, typically 1e+037
[log] - linear when unset, logarithmic when set
[init] - when set outputs
[send] - send symbol name
[receive] - receive symbol name
[label] - label
[x_off] - horizontal position of the label text relative to the upperleft corner of the object
[y_off] - vertical position of the label text relative to the upperleft corner of the object
[font] - font type
[fontsize] - font size in pixels
[bg_color] - background color
[fg_color] - foreground color
[label_color] - label color
[log_height] - logarithmic steps, accepts values from 10 to 2000, default is 256
Example:
 #X obj 39 48 nbx 5 14 -1e+037 1e+037 0 0 empty empty empty 0 -6 0 10 -262144 -1 -1 0 256;
Remarks:

This element resembles the floatatom element, but is extended with gui and logarithmic parameters and (probably) more accurate.
The attributes [font], [font_size] and [fg_color] also apply to the digits.

back to reference index

 

vsl
Description:
 Defines a vertical slider
Syntax:
 #X obj [x_pos] [y_pos] vsl [width] [height] [bottom] [top] [log] [init] [send] [receive] [label] [x_off] [y_off] [font] [fontsize] [bg_color] [fg_color] [label_color] [default_value] [steady_on_click];\r\n
Parameters:
 [x_pos] - horizontal position within the window
[y_pos] - vertical position within the window
[width] - horizontal size of gui element
[height] - vertical size of gui element
[bottom] - minimum value
[top] - maximum value
[log] - when set the slider range is outputted logarithmically, otherwise it's output is linair
[init] - sends default value on patch load
[send] - send symbol name
[receive] - receive symbol name
[label] - label
[x_off] - horizontal position of the label text relative to the upperleft corner of the object
[y_off] - vertical position of the label text relative to the upperleft corner of the object
[font] - font type
[fontsize] - font size
[bg_color] - background color
[fg_color] - foreground color
[label_color] - label color
[default_value] - default value times hundred
[steady_on_click] - when set, fader is steady on click, otherwise it jumps on click
Example:
 #X obj 50 38 vsl 15 128 0 127 0 0 empty empty empty 0 -8 0 8 -262144 -1 -1 0 1;
Remarks:

The vertical slider object and the horizontal slider are the only objects which have a default value multiplied by hundred. This purpose is unknown.

back to reference index

 

hsl
Description:
 Defines a horizontal slider
Syntax:
 #X obj [x_pos] [y_pos] hsl [width] [height] [bottom] [top] [log] [init] [send] [receive] [label] [x_off] [y_off] [font] [fontsize] [bg_color] [fg_color] [label_color] [default_value] [steady_on_click];\r\n
Parameters:
 [x_pos] - horizontal position within the window
[y_pos] - vertical position within the window
[width] - horizontal size of gui element
[height] - vertical size of gui element
[bottom] - minimum value
[top] - maximum value
[log] - when set the slider range is outputted logarithmically, otherwise it's output is linair
[init] - sends default value on patch load
[send] - send symbol name
[receive] - receive symbol name
[label] - label
[x_off] - horizontal position of the label text relative to the upperleft corner of the object
[y_off] - vertical position of the label text relative to the upperleft corner of the object
[font] - font type
[fontsize] - font size
[bg_color] - background color
[fg_color] - foreground color
[label_color] - label color
[default_value] - default value times hundred
[steady_on_click] - when set, fader is steady on click, otherwise it jumps on click
Example:
 #X obj 53 44 hsl 128 15 0 127 0 0 empty empty empty -2 -6 0 8 -262144 -1 -1 0 1;
Remarks:

The horizontal slider object and the vertical slider are the only objects which have a default value multiplied by hundred. This purpose is unknown.

back to reference index

 

vradio
Description:
 Defines a vertical radio button selector
Syntax:
 #X obj [x_pos] [y_pos] vradio [size] [new_old] [init] [number] [send] [receive] [label] [x_off] [y_off] [font] [fontsize] [bg_color] [fg_color] [label_color] [default_value];\r\n
Parameters:
 [x_pos] - horizontal position within the window
[y_pos] - vertical position within the window
[size] - horizontal size and vertical size, depending on the number of radio buttons
[new_old] - send new and old value, or only the new value
[init] - send default value on init
[number] - amount of radio buttons
[send] - send symbol name
[receive] - receive symbol name
[label] - label
[x_off] - horizontal position of the label text relative to the upperleft corner of the object
[y_off] - vertical position of the label text relative to the upperleft corner of the object
[font] - font type
[fontsize] - font size
[bg_color] - background color
[fg_color] - foreground color
[label_color] - label color
[default_value] - default value to be sent on patch load when the [init] attribute has been set.
Example:
 #X obj 48 42 vradio 15 1 0 8 empty empty empty 0 -6 0 8 -262144 -1 -1 0;
Remarks:

The purpose of the [new_old] switch is unknown.

back to reference index

 

hradio
Description:
 Defines a horizontal radio button selector
Syntax:
 #X obj [x_pos] [y_pos] hradio [size] [new_old] [init] [number] [send] [receive] [label] [x_off] [y_off] [font] [fontsize] [bg_color] [fg_color] [label_color] [default_value];\r\n
Parameters:
 [x_pos] - horizontal position within the window
[y_pos] - vertical position within the window
[size] - vertical size and horizontal size, depending on the number of radio buttons
[new_old] - send new and old value, or only the new value
[init] - send default value on init
[number] - amount of radio buttons
[send] - send symbol name
[receive] - receive symbol name
[label] - label
[x_off] - horizontal position of the label text relative to the upperleft corner of the object
[y_off] - vertical position of the label text relative to the upperleft corner of the object
[font] - font type
[fontsize] - font size
[bg_color] - background color
[fg_color] - foreground color
[label_color] - label color
[default_value] - default value to be sent on patch load when the [init] attribute has been set.
Example:
 #X obj -50 54 hradio 15 1 0 8 empty empty empty 0 -6 0 8 -262144 -1 -1 0;
Remarks:

The purpose of the [new_old] switch is unknown.

back to reference index

 

vu
Description:
 Defines a VU-meter
Syntax:
 #X obj [x_pos] [y_pos] vu [width] [height] [receive] [label] [x_off] [y_off] [font] [fontsize] [bg_color] [label_color] [scale] [?];\r\n
Parameters:
 [x_pos] - horizontal position within the window
[y_pos] - vertical position within the window
[width] - horizontal size of element
[height] - vertical size of element
[receive] - receive symbol name
[label] - label
[x_off] - horizontal position of the label text relative to the upperleft corner of the object
[y_off] - vertical position of the label text relative to the upperleft corner of the object
[font] - font type
[fontsize] - font size
[bg_color] - background color
[label_color] - label color
[scale] - when set the logarithmic scale is displayed
[?] - unknown value, default is zero
Example:
 #X obj 40 44 vu 15 120 empty empty -1 -8 0 8 -66577 -1 1 0;
Remarks:

We looked inside the source code but still couldn't see the purpose of the final value.

back to reference index

 

cnv
Description:
 Defines a canvas, a gui component
Syntax:
 #X obj [x_pos] [y_pos] cnv [size] [width] [height] [send] [receive] [label] [x_off] [y_off] [font] [font_size] [bg_color] [label_color] [?];\r\n
Parameters:
 [x_pos] - horizontal position within the window
[y_pos] - vertical position within the window
[size] - size of selectable square
[width] - horizontal size of the GUI-element
[height] - vertical size of the GUI-element
[send] - send symbol name
[receive] - receive symbol name
[label] - label
[x_off] - horizontal position of the label text relative to the upperleft corner of the object
[y_off] - vertical position of the label text relative to the upperleft corner of the object
[font] - font type
[fontsize] - font size
[bg_color] - background color
[label_color] - foreground color
[?] - unknown value, default is zero
Example:
 #X obj 27 40 cnv 15 100 60 empty empty empty 20 12 0 14 -233017 -66577 0;
Remarks:

We couldn't find the purpose of the final value.

back to reference index

 

[name]
Description:
 Defines an external subpatch or library patch
Syntax:
 #X obj [x_pos] [y_pos] [name] [p1] [p2] [p3] [...] ;\r\n
Parameters:
 [x_pos] - horizontal position within the window
[y_pos] - vertical position within the window
[name] - name of the subpatch / library patch
[p1] [p2] [p3] [...] - optional parameters
Example:
 #X obj 121 102 subpatch;
Remarks:

If the external object isn't in the loaded libraries PureData searches in the folder of the main frame (window) to locate the object.

back to reference index

 

pd
Description:
 Defines an internal subpatch
Syntax:
 #X restore [x_pos] [y_pos] pd [name];\r\n
Parameters:
 [x_pos] - horizontal position within the window
[y_pos] - vertical position within the window
[size] - size of selectable square
[width] - horizontal size of the GUI-element
[name] - name of the subpatch
Example:
 #N canvas 0 0 454 304 inc 0;
#X obj 34 40 inlet;
#X obj 34 95 outlet;
#X obj 34 67 + 1;
#X connect 0 0 2 0;
#X connect 2 0 1 0;
#X restore 90 124 pd inc;
#X floatatom 90 99 5 0 0 0 - - -;
#X floatatom 90 151 5 0 0 0 - - -;
#X connect 0 0 2 0;
#X connect 1 0 0 0;
Remarks:

Naturally the restore element which invokes a subpatch is preceded with a canvas element and the subpatch elements.
Objects within a subpatch are counted seperately from a parent frame (window).

back to reference index

 

restore
Description:
 Ends a canvas definition
Syntax:
 #X restore [x_pos] [y_pos] [type] [name];\r\n
Parameters:
 [x_pos] - horizontal position within the window
[y_pos] - vertical position within the window
[type] - type of canvas, values are either "graph" or "pd"
[name] - name of the subpatch, only used when the [type] attribute is set to "pd"
Example:
 #N canvas 0 0 450 300 graph2 0;
#X coords 0 1 100 -1 200 140 1;
#X restore 27 30 graph;
Example:
 #N canvas 0 0 452 302 subpatch 0;
#X restore 64 69 pd subpatch;
Remarks:

The restore element is used only in combination with canvas elements. There are two uses:
In the first example it defines a graph, in this case a coords element is required.
In the second example it defines a subpatch. In this case only the canvas attribute [name] and the restore attribute [name] should correlate.

back to reference index

 

symbolatom
Description:
 Defines an symbol box
Syntax:
 #X symbolatom [x_pos] [y_pos] [width] [lower_limit] [upper_limit] [label_pos] [label] [receive] [send];\r\n
Parameters:

[x_pos] - horizontal position within the window
[y_pos] - vertical position within the window
[width] - amount of digits/characters
[lower_limit] - minimum value
[upper_limit] - maximum value
[label_pos] - label position relative to floatatom position. 0 = left, 1 = right, 2 = top, 3 = bottom
[label] - label
[receive] - receive symbol value
[send] - send symbol value
Example:
 #X symbolatom 36 37 10 0 0 0 - - -;
Remarks:

When the value of [upper_limit] minus the value of [lower_limit] is less than one, PureData resets these values both to zero.
Symbolatom and floatatom are the only elements that uses "-" characters to indicate that no value has been assigned to its attributes [label], [receive] and [send].

back to reference index

 

text
Description:
 Defines a comment
Syntax:
 #X text [x_pos] [y_pos] [comment];\r\n
Parameters:

[x_pos] - horizontal position within the window
[y_pos] - vertical position within the window
[comment] - custom string, spaces allowed
Example:
 #X text 28 25 comment;
Remarks:

ASCII return codes 13 and 10 are not stored, a semicolon character is preceded with the escape character backslash.

back to reference index


+ Valid HTML 4.01! +

+ + -- cgit v1.2.1