forked from pure-data/pure-data
-
Notifications
You must be signed in to change notification settings - Fork 1
/
x2.htm
1711 lines (1361 loc) · 86.1 KB
/
x2.htm
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<HTML lang="en">
<HEAD>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<TITLE>Pd Manual 2</TITLE>
<meta http-equiv="Content-Type" content="text/html">
<link rel="stylesheet" type="text/css" href="pdmanual.css" media="screen">
<link rel="icon" type="image/png" href="favicon.ico">
</HEAD>
<BODY>
<div class="butt">
</div>
<div id=corpus>
<H2>Pd Manual chapter 2: Theory of operation</H2>
<P>
<A href="index.htm#s2"> back to table of contents</A>
<BR><BR>
</P>
<P>
<P> The purpose of this chapter is to describe Pd's design and how it is
supposed to work. Practical details about how to obtain, install, and run Pd
are described in the <A href=x3.htm>next chapter</A>. Links to more extensive
guides (and to more theoretical information about computer music) can be found
in the <A href=x1.htm>previous chapter</A>.
<H3> <A id=s1> 2.1. Overview </A> </H3>
<P> Pd is a real-time graphical programming environment designed for audio processing,
but can be expanded to graphical images and more with external packages. It resembles
the MAX system but is much simpler and more portable. For example, with Peter Brinkmann's
libpd you can have Pure Data as an embeddable audio synthesis library. Also Pd has an
experimental facility not present in MAX that is provided for defining and accessing
data structures.
<P> Even though it is light and portable, Pd has many external packages that expand its
features, most for audio and control processing such as ceammc, cyclone, else, iemlib,
zexy and countless others. External lbraries that add graphical processing include like
Mark Dank's GEM package which expands Pd to be used for simultaneous computer animation
and Zack Lee's Ofelia that allows you to use openFrameworks and Lua within Pd for creating
audiovisual artwork or multimedia applications such as games. For details on installing and
managing packages, refer to the <A href=x3.htm>Externals</A> chapter.
<H3> <A id=s1.1> 2.1.1. The main window, canvases, and printout </A> </H3>
<P> When Pd is running, you'll see a main "Pd" window, and possibly one or more
"canvases" or "patches". The main Pd window looks like this:
<CENTER><P>
<IMG src="fig1.1.png" ALT="pd window">
</P></CENTER>
<P> At the top you can see the Menu entries: <b>File</b>, <b>Edit</b>, <b>Put</b>,
<b>Find</b>, <b>Media</b>, <b>Window</b> and <b>Help</b> (on macs this is shown at a
top bar on the computer screen and there is a first <b>Pd</b> menu entry). At upper
right there is a "DSP" toggle box to turn audio processing on and off globally. When
audio is on, Pd is computing audio samples in realtime according to whatever patches
you have open (whether they are visible or not). Turning off the audio halts the
computation and releases any audio devices that Pure Data is utilizing. You can
choose Audio in "preferences" as described in <A href=x3.htm>next chapter</A>.
<P> The <b>Media menu</b> offers shortcuts to toggle audio on and off. Use <kbd>Ctrl + /</kbd>
('Control' key on PCs or 'Command' key on Apple computers plus the '<b>/</b>' key) to turn audio
on, and <kbd>Ctrl + .</kbd> to turn it off. You can check input RMS audio level if you select
"Test Audio and MIDI" and make other Audio and MIDI tests (more about it in <A href=x3.htm>3.1.
Audio and MIDI</A>).
<CENTER><P>
<IMG src="fig-ch2-console-media-menu.png"
ALT="media menu">
</P></CENTER>
<P> The bottom part of the Pd window is an area for printout from objects in patches,
and/or for messages from Pd itself. If the Pd window is focused, the menus and console
font size can be changed using the <b>Font</b> dialog entry in the <b>Edit Menu</b>
(shown in detail below). Make your adjustments if you are having troubles reading
on HiDPI screens. Also in the <b>Edit Menu</b> you can clear all messages printed
in the Pd window with the 'Clear Console' entry (<kbd>Shift + Ctrl + L</kbd> shortcut).
On the <b>Window menu</b> you find the 'Pd Window' entry (with the <kbd>Ctrl + R</kbd>
shortcut), which brings the Pd window to the front or sends it behind the Pd window in
focus.
<CENTER><P>
<IMG src="fig-ch2-console-edit-menu.png"
ALT="edit menu">
</P></CENTER>
<P> Pd documents (or files) are called "patches" or "canvases". Each open document has
one main window and any number of sub-windows. The sub-windows can be opened and closed
but are always running, whether you can see them or not. You can create and open patches
via the <b>File Menu</b> as well as close and save them (note the handy shortcuts).
<CENTER><P>
<IMG src="fig-ch2-file-menu.png" ALT="file menu">
</P></CENTER>
In Pcs, this menu shows the <kbd>Ctrl + Q</kbd> entry to quit Pd, which prompts you
to confirm the action (in macs, this is under the <b>Pd Menu</b>). To quit without
confirmation, use <kbd>Shift + Ctrl + Q</kbd>.
<P> Here is a simple Pd patch:
<CENTER><P>
<IMG src="fig1.2.png" ALT="hello world patch">
</P></CENTER>
<P>There are four <I> text boxes </I> in this patch: a number box (showing zero),
an object box showing "print", and two comments. The number box and the object
box are connected, the number box's output to the [print] object box's input.
Boxes may have zero or more inputs and/or outputs, with the inputs on top and the
outputs on bottom. When clicking and dragging on the number box, the valus are
printed on the main "Pd" window.
<H3> <A id="s1.2"> 2.1.2. Object boxes </A> </H3>
<P> Pd patches can have four types of boxes: <I> object, message, GUI, </I>
and <I> comment </I>. The <b>Put Menu</b> offers a list with such boxes. Note
that many of these are individual GUI (graphical user interface) boxes. There
are also entries for array and graph that are explained later. (INCLUDE PIC)
<P> You create a specific <I> object </I> by typing a text into the box. The text
is divided into <I> atoms </I> separated by white space. The first atom specifies
what type of object Pd will make and needs to be a symbol, and the other atoms,
called <I> creation arguments </I>, tell Pd how to initialize the object. You can
type, for example, "+ 13".
<CENTER><P>
<IMG src="fig1.3.png" ALT="object">
</P></CENTER>
<P>Here, the "+" specifies the <I> class </I> of the object. In this case the
object will carry out additions, and the "13" initializes the value to add.
<P> Atoms are either numbers or <I> symbols </I> like "+". Anything that is not a
valid number is considered a symbol. Valid numbers may or may not have a decimal
point (for instance, 12, 15.6, -.456), or may be written in exponential notation
(such as "4.5e6", which means "4.5 multiplied by 10 six times, i.e., 4500000).
Negative exponentials divide by 10 (so that 1.23e-5 comes to 0.0000123).
<P> Non-valid numbers which are read as symbols include things like "+5" and "0..6"
as well as words and names such as "Zack" or "cat". The symbols "gore", "Gore", and
"GORE" are all distinct.
<P> The text you type into an object box determines how many and what kinds of
inlets and outlets the object will have. Certain classes, such as [+], consistently
maintain a fixed configuration of inlets and outlets. However, for other classes,
the number and arrangement of inlets and outlets can vary based on the arguments
provided at creation.
<P>Here for example is a simple MIDI synthesizer:
<CENTER><P>
<IMG src="fig1.4.png" ALT="simple MIDI synthesizer">
</P></CENTER>
<P>This patch mixes <I> control </I> objects ([notein], [stripnote], and [ftom]) with
<I> tilde </I> objects [osc~], [*~], and [dac~]. The control objects carry out their
function sporadically, as a result of one or more types of <I> event </I>. In
this case, incoming MIDI note messages set off the control computation. The
result of the computation is, when the note happens to be a "note on" (and not
a "note off"), to compute the frequency in cycles per second and pass it on to
the oscillator ([osc~]).
<P> The second half of the patch (the [osc~], [*~], and [dac~] objects) computes
audio samples. The [osc~] object is acting as the interface between the two regimes,
in that it takes control messages to set its frequency but outputs an audio sine wave
to [*~]. The connections in the patch (the lines between the boxes) are also of two
types: control and signal. Note that they are visually distinct, where signal connections
are thicker than control connections. The type of connection depends on the outlet it comes
from; in the patch above, the two bottom connections are signal and the others are control.
In general, a control connection may be made to a signal inlet; if numbers are sent over it
they are automatically converted to signals. Signal connections may not be made to control
inlets; some sort of explicit conversion must be specified.
<P> Audio signals aren't sporadic; they are continuous streams of numbers. As a result,
tilde objects act under very different rules from control objects. If the DSP is set to 'On',
the audio portion of the patch is always running, whether MIDI messages arrive or not. On the
other hand, the function of control computations is to insert calculations between the audio
computation, which may change audio computation parameters (such as the frequency of an
oscillator in this case).
<H3> <A id="s1.3"> 2.1.3. Message and GUI boxes </A> </H3>
<P>The border of a box tells you how its text is interpreted and how the box
functions. Object boxes (as in the previous example) are rectangular and use
the text to create objects when you load a patch or type text onto a new one.
That is, the contents of an object box describe a message which is sent to Pd
to create the object. If you retype the text in an object box, the old one is
discarded and a new one is created, using the new creation arguments.
<P> <I> Message </I> boxes have a different shape and interpret the text as a
message to send whenever the box is activated (by an incoming message or via a
mouse click). The message may be sent many times while the patch is running
(as opposed to object boxes whose message is used once to create the object).
Instead of going straight to Pd, the message box's message (or messages) go either
to its outlet or to other specified receiving objects. In the example below,
the message box, when clicked, sends the message "21" to an object box which
adds 13 to it.
<CENTER><P>
<IMG src="fig1.5.png" ALT="[message( --> [object] -> [number]">
</P></CENTER>
<P> The third box shown is a <I> GUI </I> ("graphical user interface") box. Pd has three
basic GUI boxes. In addition to number boxes (as in this example), there are boxes to
display and edit symbols or arbitrary lists of atoms. Pd also comes with a set GUIs that
include toggles, sliders, radio buttons and so on. These other GUIs are also known as
"iemGUIs" and they used to be an external library package, but were incorporated natively
into Pd in version 0.34 (they can still be created from object boxes though).
<P> You can interact with GUIs in many ways. Whereas the appearance of an object
or message box is static when a patch is running, a number box's contents (the text)
changes to reflect the current value held by the box. You can also use a number box
as a control by clicking and dragging up and down, or by typing values in it and
hitting enter. (more details on how this and any other GUIs work is available in the
help files; see <A href="x2.htm#s2.7"> Context menu for 'Properties', 'Open' and 'Help'
</A> to find out how to look this up).
<H3> <A id="s1.4"> 2.1.4. Patches and files </A> </H3>
<P> As mentioned before, You can create or open a Pd file from the
<b>File Menu</b> as well as close and save them.
<P>You can also edit the font size of of a patch if its window is focused, just
use the <b>Font</b> dialog entry again from the <b>Edit menu</b>. The font size
setting of patch gets saved within the patch file.
<P>When you save a patch to a file, Pd doesn't save the entire state of all the
objects in the patch, but only what you see: the objects' creation arguments
and their interconnections. Nonetheless, the [savestate] object offers a mechanism
to save the state of abstractions (see <A href="x2.htm#s8"> Subpatches </A>). Also,
certain data-storage objects have functions for reading and writing other files to
save and restore their internal state.
<P>Pd finds files using specified <I> paths </I>. Most objects which can read files
search for them along the search paths, but when Pd writes files they go to
the directory where the patch was found.
<H3> <A id=s2> 2.2. Editing Pd patches </A> </H3>
<P> A patch can be in edit or run mode; this really only changes how mouse clicks
affect the patch. In run mode, the mouse cursor is an arrow. A patch is in run mode
when you first open it. Select "edit mode" in the <b>Edit menu</b> to check it on
and the cursor will change to the image of a hand. Unchecking it in the menu sets
back to run mode. You can also use the <kbd>Ctrl + E</kbd> shortcut to get in and
out of Edit mode.
<CENTER><P>
<IMG src="fig-ch2-editmode.png" ALT="edit mode">
</P></CENTER>
<H3> <A id=s2.1> 2.2.1. Edit and Run mode </A> </H3>
<p> In edit mode, you can move boxes around by clicking on them and dragging.
You can also edit text, create, delete objects and make or cut connections.
More details to come.
<p> Normally, when you are in a performance you will stay in run mode. In this
mode the cursor is a slightly tilted arrow that points straight up when you are
able to click on an object. In run mode, you mostly click and interact with
GUIS (like the number box) and message boxes (which are used as controls to
send messages to other objects).
<p> If you are predominantly editing a patch but would like to quickly go to
run mode just to click on something like a message, you can just press <kbd>Ctrl</kbd>
key and you'll note the shape of an arrow is back until you release the key.
<H3> <A id=s2.2> 2.2.2. Creating boxes </A> </H3>
<P> You can create boxes (objects, messages, GUIs, and comments) using the
<b>Put Menu</b>. Note the handy accelerators.
<CENTER><P>
<IMG src="fig-ch2-put-menu.png" ALT="put menu">
</P></CENTER>
<P> If you are in run mode and click on an entry on the <b>Put Menu</b>
or use a shortcut, Pd goes automatically into edit mode. When you create boxes
this way, they are automatically selected and follow the mouse cursor position;
drag them around as desired until you click to position them where you want.
Alternatively you can hit <kbd>Esc</kbd> to deselect it, which will also place
the object. Object and message boxes are empty at first, you can move them and
also position them by just start typing into them.
<P> You may find it more convenient to select a box and "duplicate" it than to
use the <b>Put Menu</b>. If you select and duplicate several items, any connections
between them will be duplicated as well.
<H3> <A id=s2.3> 2.2.3. Selecting items and moving them or "tidying them up" </A> </H3>
<P>In Edit mode you can select or unselect one or more objects. Boxes in a Pd
window may be individually selected by clicking on them. If you don't release
the mouse button you can select a box and drag it around. To select more than one
box you may use <kbd>Shift + Click</kbd> on each item. You then can click again on
one of the selected boxes to move them around. Alternatively you click on a blank
portion of the window and drag the cursor to select all objects within a rectangle
(then click again on one of the selected boxes to move them as well).
<P>When you have one or more boxes selected, you can also move them using
<kbd>Arrow keys</kbd>, which moves items one pixel in the direction of
the arrows. You can also use <kbd>Shift + Arrow keys</kbd> to move items
10 pixels in the desired direction.
<P>Clicking on an unselected object, message, or comment box and releasing the
click makes the text active, i.e., ready to be text edited. (If you select using
the rectangle method or <kbd>Shift + Click</kbd>, the text isn't activated.) Once
you've activated a text box, you may type into it (replacing the selected text).
Use <kbd>Arrow keys</kbd> to navigate through the text or use the mouse to click
and drag to change the text selection and edit it.
<P>If you select boxes that are connected, the connections (patch cords) are
also selected and moved around. You can't just select patch cords with click
and drag and you can only select a single connection by clicking on it.
<P>The 'Tidy Up' entry in the <b>Edit menu</b> allows you to try and align
objects that are not perfectly aligned. You can select boxes arranged in a
horizontal row and use the shortcut <kbd>Shift + Ctrl + R</kbd> to try and
align them perfectly horizontally. Similarly, this can be applied to vertically
align a column of objects. Rectangular selections of object are also possible,
but aligning horizontally and vertically separately tends to yield better results.
<CENTER><P>
<IMG src="fig-ch2-selecting-items-and-moving-them-or-tidying-them-up.png"
ALT="selecting items and moving them or tidying them up">
</P></CENTER>
<H3> <A id=s2.4> 2.2.4. Delete, cut, copy and paste </A> </H3>
<P>In edit mode, if you select one connection by clicking on it, you can delete
it by hitting the <kbd>Backspace</kbd> or <kbd>Delete</kbd> key. Similarly, you can
select one box (without activating a text selection) and delete it. Connections of
a deleted box are also deleted. A multiple selection of boxes can also be deleted.
The "Select All" entry on the Edit Menu selects all items in a patch window.
<P>For one or more selected boxes and their connections you can also "cut", "copy"
and "paste" using menu items. Notice you can "cut" or "copy" and then "paste" the
selection in a different window. When pasted, the items stay selected, so you can
click on one of the selected items and move the whole group around by dragging.
<P> Note that pasting inserts the selection at the same position it was copied,
unless the place is already taken when there is a small offeset. The "duplicate"
menu item performs a copy and paste with a small offset (since the original
selection remains in the original position). You can then click on an item in
the duplicated selection and drag them all together to a new spot in the patch
window.
<P> To deselect, you can either click on an empty area of your patch or press
the <kbd>Esc</kbd> key.
<P> For a selected object box, message box, or comment with active text, you can
also use the copy, cut, and paste commands for the selected text. The text selection
functionality for cut/copy/paste is integrated with the OS, enabling you to copy
and paste text between Pure Data and other software applications.
<P> While you can cut or copy a selection within a patch and paste it into a
different window within Pure Data, the cut/paste functionality for patch elements
is not integrated with the operating system clipboard. This limitation means you
cannot paste between different versions or flavors of Pure Data. Additionally,
it is not possible to copy from a patch and paste into a Pure Data subprocess
instantiated via a [pd~] object.
<H3> <A id=s2.5> 2.2.5. Changing the text </A> </H3>
<P> To change the text in an object, message or comment, you can select it and then
edit the text. If you only click once, the entire text is selected and your
typing will replace everything. Click again to position the cursor or drag to
select a portion of the text to retype. You can also use cut/copy/paste as mentioned.
<CENTER><P>
<IMG src="fig-ch2-changing-text.png"
ALT="changing text">
</P></CENTER>
<P> If you wish to displace a box whose text is activated you need to first deselect
it (by clicking outside it or using <kbd>Esc</kbd>); otherwise you will be selecting
text instead of moving the box.
<P> <I> The updated text only becomes part of the patch when you deselect the
object. </I> As already mentioned, changing the text in an "object" box deletes
the old object and creates a new one; so the internal state of the old one is
completely lost.
<H3> <A id=s2.6> 2.2.6. Connecting boxes </A> </H3>
<P> This subsection only describes the simplest way to connect two boxes. For
more advanced and convenient techniques and shortcuts, refer to the next section.
<P> To create a connection in edit mode, move your mouse into the the area of
an outlet. Note that the cursor becomes a circle, indicating that you can click
and drag to create a connection. Drag the cord into an outlet area, where
you'll see again the circle shaped cursor, signaling that you can release
the mouse button to create a connection. You can release the mouse button
anywhere within the top area of the target object and the connection will
be made to the nearest inlet.
<CENTER><P>
<IMG src="fig-ch2-connecting-boxes.png"
ALT="connecting boxes">
</P></CENTER>
<P> As already mentioned, connections are removed by selecting them and
hiting <kbd>Backspace</kbd> or <kbd>Delete</kbd> key.
<H3> <A id=s2.7> 2.2.7. Context menu for 'Properties', 'Open' and 'Help' </A> </H3>
<P> All the "clicking" mentioned above is done with the left mouse button.
The right button, instead, opens a context menu offering "Properties",
"Open" and "Help". For Apple users who may only have one button on their
mouse, double-clicking or <kbd>Alt + Click</kbd> are mapped to right-click
and on trackpads you can click with two fingers.
<P> Selecting "Help" on an object opens a patch explaining and demonstrating
the object. "Help" for the canvas as a whole (right-clicking outside any object)
gives a list of all built-in objects.
<P> The "Open" menu item is only enabled if you right-click on a subpatch
(see <A href="x2.htm#s8"> Subpatches </A>) and prompts Pd to open it.
Ordinary subpatches may also be opened by simply clicking on them, but for
"graph-on-parent" subpatches, this is the only method available.
<P> The "Properties" dialog allows you to change certain settings of GUI
boxes or of the patch itself (when clicking outside any box).
<H3> <A id="s3"> 2.3. Advanced patch editing </A> </H3>
<P> This section describes advanced techniques and shortcuts for editing patches.
<H3> <A id="s3.1"> 2.3.1. Tab navigation </A> </H3>
<P> When a single box is selected, pressing <kbd>Tab</kbd> allows you to
navigate and change the selection to other objects in the sequence determined
by the order of their creation. Pressing <kbd>Tab</kbd> cycles through the
objects from the earliest created to the next, and upon reaching the last box
in the window the selection loops back to the first one. Conversely, you can
press <kbd>Shift + Tab</kbd> to navigate in reverse order, moving from the
most recently created objects back towards the first created ones.
<CENTER><P>
<IMG src="fig-ch2-tab-navigation-boxes.png"
ALT="tab navigation boxes">
</P></CENTER>
<P> Using <kbd>Tab</kbd> also works in a similar way for patch cords if
you have one selected. You can move from first to last with <kbd>Tab</kbd>
and from last to first with <kbd>Shift + Tab</kbd>.
<CENTER><P>
<IMG src="fig-ch2-tab-navigation-cords.png"
ALT="tab navigation cords">
</P></CENTER>
<P> If you're creating a connection by clicking on an outlet and dragging a
patch cord, you can also use <kbd>Tab</kbd> to cycle through outlets.
The navigation order is left to right and it also cycles back. Pressing
<kbd>Shift + Tab</kbd> navigates from right to left.
<CENTER><P>
<IMG src="fig-ch2-tab-navigation-inlets-outlets.png"
ALT="tab navigation inlets outlets">
</P></CENTER>
<P> In Linux and Windows you can also cycle between inlets. This is currently
not possible on macOS. When dragging a connection into an inlet area, without
releasing the mouse, you can use <kbd>Tab</kbd> to navigate to the next inlet,
or <kbd>Shift + Tab</kbd> to navigate to the previous one.
<H3> <A id="s3.2"> 2.3.2. Autopatching </A> </H3>
<P> By default, Pd has an 'autopatching' mode set to on. You can disable it
via startup flags (see '-autopatch' flag <a href="x3.htm#s4"> Preferences
and startup options </A>). This works with the shortcuts from the <b>Put menu</b>
for inserting boxes. If you have a selected box and use a shortcut to
create another one (such as <kbd>Ctrl + 1</kbd> to create an object box),
the created box is placed below the selected object and a connection is made
from the first outlet of the selected object into the inlet of the newly
created object (granted that these objects have an outlet and an inlet for the
connection to happen).
<P> Once the new box is created, it is also selected, so you can continue with
autopatching by adding yet more boxes. In the case of object and message boxes
you can also start typing text into it before autopatching into another newly
created box, since when you autopatch for the next one, the object or message
box gets deselected and therefore created.
<CENTER><P>
<IMG src="fig-ch2-autopatching-objects.png"
ALT="autopatching objects">
</P></CENTER>
<P> You can also autopatch into a newly created subpatch (see <A href="x2.htm#s8">
Subpatches </A>). By creating an object box and typing [pd], as soon as you
deselect the object, a subpatch is created with an inlet - either a control
inlet ([inlet]) if the object above is a control object, or a signal inlet
([inlet~]) if it is a tilde object instead.
<CENTER><P>
<IMG src="fig-ch2-autopatching-subpatches.png"
ALT="autopatching subpatches">
</P></CENTER>
<H3> <A id="s3.3"> 2.3.3. Duplicate connections </A> </H3>
<P> If you select a connection between two objects that have more than one
outlet and inlet for connections, you can use <kbd>Ctrl + D</kbd> to duplicate
and create more connections.
<CENTER><P>
<IMG src="fig-ch2-duplicate-connections.png"
ALT="duplicate connections">
</P></CENTER>
<H3> <A id="s3.4"> 2.3.4. Managing connections with the Shift key </A> </H3>
<P> You can swap connections if you selected a connection and use
<kbd>Shift + Click</kbd> on another one.
<CENTER><P>
<IMG src="fig-ch2-managing-connections-shift-click.png"
ALT="managing connections shift click">
</P></CENTER>
<P> You can "fan out" connections when no boxes are selected. You can
start creating a connection by clicking an outlet and dragging a cord
and then use <kbd>Shift</kbd> when you reach the inlet destination
(without releasing the mouse button). This "fans out" out and creates
another connection from the outlet for you to drag somewhere else and
connect the same outlet to to multiple inlets sequentially.
<CENTER><P>
<IMG src="fig-ch2-managing-connections-drag-fan-out.png"
ALT="managing connections drag fan out">
</P></CENTER>
<P> Also for fanning out, if you have a group of target boxes that are selected,
you can drag a cord from an outlet of an unselected box and press <kbd>Shift</kbd>
to create a connection into the same inlet number of the selected boxes (which do
not need to be of the same type or class).
<CENTER><P>
<IMG src="fig-ch2-managing-connections-fan-out.png"
ALT="managing connections fan out">
</P></CENTER>
<P> You can create a connection from the same outlet number of multiple
objects to a single inlet. If you have a selection of source boxes, you can
drag a cord from one of their outlets into another box and press <kbd>Shift</kbd>
to create multiple connections from the same outlet number of the selected boxes
(which do not need to be of the same type or class).
<CENTER><P>
<IMG src="fig-ch2-managing-connections-fan-in.png"
ALT="managing connections fan in">
</P></CENTER>
<P> You can connect multiple outlets and inlets of 2 boxes if you have 2 selected
boxes. Start creating a connection and click <kbd>Shift</kbd> at completion.
This creates all possible connections starting from the chosen outlet and inlet.
<CENTER><P>
<IMG src="fig-ch2-managing-connections-box-to-box.png"
ALT="managing connections box to box">
</P></CENTER>
<P> You can connect outlets of multiple boxes into multiple inlets of one box.
If there's a selected group of boxes, you start creating a connection into an
inlet of a box that is part of the selection. Then you can press <kbd>Shift</kbd>
so connections are made from the same outlet number of all source boxes (which do
not need to be of the same type or class) into separate inlets, starting from the
chosen inlet.
<CENTER><P>
<IMG src="fig-ch2-managing-connections-many-to-one.png"
ALT="managing connections many to one">
</P></CENTER>
<P> You can spread multiple outlets of one box into same inlets of other boxes.
Similarly to the scenario above, you can start dragging from one outlet of a
selected box with multiple outlets to an inlet of one of many selected boxes.
In this case, when you press <kbd>Shift</kbd>, all possible connections are
made from the outlets of the source box to the same inlet numbers of the target
boxes.
<CENTER><P>
<IMG src="fig-ch2-managing-connections-one-to-many.png"
ALT="managing connections one to many">
</P></CENTER>
<H3> <A id="s3.5"> 2.3.5. (Dis)Connect selection </A> </H3>
<P> This is a menu entry in the <b>Edit menu</b>, also available via the shortcut
<kbd>Ctrl + K</kbd>. It allows you to connect and disconnect selected boxes in
different ways.
<CENTER><P>
<IMG src="fig-ch2-dis-connect-menu.png"
ALT="dis/connect menu">
</P></CENTER>
<P> For 2 selected boxes you can use <kbd>Ctrl + K</kbd> to connect
them. Repeat using <kbd>Ctrl + K</kbd> to make multiple connections
from possible remaining outlets to inlets.
<CENTER><P>
<IMG src="fig-ch2-dis-connect-parallel.png"
ALT="dis/connect parallel">
</P></CENTER>
<P> For 2 selected audio objects, if the origin object has a single outlet
and the target object has many inlets, you can repeatedly use <kbd>Ctrl + K</kbd>
to fan out and connect the same outlet to all inlets.
<CENTER><P>
<IMG src="fig-ch2-dis-connect-fan-out-audio.png"
ALT="dis/connect fan out audio">
</P></CENTER>
<P> For last, you can include or bypass a box into or from a connection
(being it any connection from any outlet into any inlet). To include a box,
you can select it and the connection between the other 2 boxes by using
<kbd>Shift + Click</kbd> and then use <kbd>Ctrl + K</kbd> to include
the selected box into the connection. Alternatively, you can select the 3
boxes with a connection between 2 of them and then use <kbd>Shift + Click</kbd>
to include the third one in the connection.
<CENTER><P>
<IMG src="fig-ch2-dis-connect-insert-box-to-connection.png"
ALT="dis/connect insert box to connection">
</P></CENTER>
<P> To bypass a box, you can select 3 boxes connected in a row and use
<kbd>Ctrl + K</kbd> to bypass and remove the middle box from the connection.
<CENTER><P>
<IMG src="fig-ch2-dis-connect-exclude-box-from-connection.png"
ALT="dis/connect exclude box from connection">
</P></CENTER>
<H3> <A id="s3.6"> 2.3.6. Triggerize </A> </H3>
<P> The 'Triggerize' entry in the <b>Edit menu</b> with the <kbd>Ctrl + T</kbd>
shortcut was designed to insert a [trigger] object (in its abbreviated form [t]).
When you select a single box that is connected to many inlets of a single or
multiple boxes use "Triggerize" to insert this object, which is briefly described
in <A href="x2.htm#s4.3"> Hot and cold inlets and right to left outlet order </A>.
<P> The [trigger] object is widely used in Pd to control the order of execution
from right to left. 'Triggerize' then creates the [trigger] object taking into
account the order in which the connections were made, where the first connection
starts at the rightmost outlet of [trigger] and continues to the leftmost.
<CENTER><P>
<IMG src="fig-ch2-triggerize-object.png"
ALT="triggerize object">
</P></CENTER>
<P> The 'Triggerize' option can also be used to insert a dummy object.
To do so, select a connection and use <kbd>Ctrl + T</kbd>. For a control
connection, a [t a] object is created with the text selected, so you
can type another text to include another object instead. For a signal
connection, a [pd nop~] subpatch is created, also with the text selected
for you to replace for a new object.
<CENTER><P>
<IMG src="fig-ch2-triggerize-insert-box-to-connection.png"
ALT="triggerize insert box to connection">
</P></CENTER>
<H3> <A id="s3.7"> 2.3.7. Paste replace </A> </H3>
<P> The "Paste Replace" entry in the <b>Edit menu</b> doesn't have a
shortcut and performs a special paste operation where it replaces a selection
of boxes for another kind. For example, first copy one box such as a
[float] object. Then select a group of boxes of the same type, for
instance, a group of object boxes (note that they don't need to be
of the same class). Now go to the <b>Edit menu</b> and select "Paste Replace".
All the selected boxes of the same type get replaced by the copied box
and connections are preserved.
<CENTER><P>
<IMG src="fig-ch2-paste-replace-menu.png"
ALT="paste replace menu">
</P></CENTER>
<P> Alternatively, you can copy a number box instead of a [float] object
and replace it in the selected group of objects, or in a selected group
of another kind, such as message boxes. Note that the object types in Pd
are: objects, messages, GUIs and comments, whereas 'IEMguis' are actually
treated in this case as regular object boxes. Hence, the GUI boxes are
only the number box, the symbol box and the list box. Also note that
these three GUIs are not of the same kind for the purpose of "Paste Replace".
A subpatch or an abstraction can also be used for "Paste Replace" and they
count in the same group of objects.
<CENTER><P>
<IMG src="fig-ch2-paste-replace-boxes.png"
ALT="paste replace boxes">
</P></CENTER>
<P> If you have a selection of objects to replace that includes different
types of objects, the "Paste Replace" will only replace the boxes of the
same type that was copied.
<CENTER><P>
<IMG src="fig-ch2-paste-replace-similar-type.png"
ALT="paste replace similar type">
</P></CENTER>
<H3> <A id="s4"> 2.4. Messages </A> </H3>
<P> In Pd, objects intercommunicate by sending messages and/or audio signals.
Pd messages are sporadic, like MIDI messages or music N "Note cards."
<H3> <A id="s4.1"> 2.4.1. Anatomy of a message </A> </H3>
<P>Messages contain a selector followed by
any number of arguments. The selector is a symbol, which appears in the patch
as a non-numeric string with no white space, semicolons, or commas. The
arguments may be symbols or numbers. Numbers in Pd are kept in 32-bit floating
point, so that they can represent integers exactly between −16777216 and
16777216. (In Max, there are separate data types for integers and floating
point numbers; Pd uses only float.)
<P> When a message is passed to something (which is often an inlet of a box
but could be anything that can receive a message), the selector of the message
is checked against the receiver. If the receiver recognizes messages of that
selector, it carries out some corresponding action. For instance, here is a
[float] object:
<CENTER><P>
<IMG src="fig3.1.png" ALT="float object">
</P></CENTER>
<P> The two rectangles at the top are usually both called "inlets" but
the one at the left directs incoming messages to the "float" object itself,
whereas the one at the right directs messages to an auxiliary "inlet"
object. The float object proper (represented by the left-hand inlet) accepts
messages with selector "float" and "bang". The right-hand inlet takes only
the message selector "float". These two selectors, along with "symbol" and
"list", are usually used to denote an object's main action, whatever it may be,
so that objects can be interconnected with maximum flexibility.
<P> It is possible to type messages which start with a number,
which cannot be used as a selector. A single number is always given the
"float" selector automatically, and a message with a number followed by other
arguments is given the selector "list".
<H3> <A id="s4.2"> 2.4.2. Depth first message passing </A> </H3>
<P> In Pd whenever a message is initiated, the receiver may then send out
further messages in turn, and the receivers of those messages can send yet
others. So each message sets off a tree of consequent messages. This tree is
executed in depth first fashion. For instance in the patch below:
<CENTER><P>
<IMG src="fig3.2.png" ALT="depth first message passing">
</P></CENTER>
<P> the order of arrival of messages is either A-B-C-D or A-C-D-B. The "C"
message is not done until the "D" one is also, and the "A" is not done until
all four are. It is indeterminate which of "B" or "C" is done first; this
depends on what order you made the connections in (in Max, it's automatically
sorted right to left).
<P> Message-passing can give rise to infinite loops of the sort shown here:
<CENTER><P>
<IMG src="fig3.3.png" ALT="infinite message passing loop">
</P></CENTER>
<P> Here the left-hand [+ 1] can't finish processing until the right-hand one has
been sent the result "2", which can't finish processing that until the
left-hand one has been sent "3", and so on. Pd will print an error message
reporting a "stack overflow" if this happens.
<P> However, it is legal to make a loop if there is a [delay] object somewhere
in it. When [delay] receives a message it schedules a message for the
future (even if the time delay is 0) and is then "finished;" Pd's internal
scheduler will wake the delay back up later.
<H3> <A id="s4.3"> 2.4.3. Hot and cold inlets and right to left outlet order </A> </H3>
<P> With few exceptions (notably [timer]), objects treat their leftmost
inlet as "hot" in the sense that messages to left inlets can result in output
messages. So the following is a legal (and reasonable) loop construct:
<CENTER><P>
<IMG src="fig3.4.png" ALT="hot and cold inlets">
</P></CENTER>
<P>Here the [f] object is an abbreviation for [float]. Note that the [+ 1] output is
connected to the right-hand inlet of [f]. This "cold" inlet merely stores the
value for the next time the [f] is sent the "bang" message.
<P>It is frequently desirable to send messages to two or more inlets of an object
to specify its action. For instance, you can use [+] to add two numbers; but
to do it correctly you must make sure the right hand inlet gets its value
first. Otherwise, when the left hand side value comes in, [+] will carry out
the addition (since the left hand inlet is the "hot" one) and will add this
value to whatever was previously sitting in the right hand inlet.
<P> Problems can arise when a single outlet is connected (either directly or
through arbitrarily long chains of message passing) to different inlets of a
single object. In this case it is indeterminate which order the two inlets will
receive their messages. Suppose for example you wish to use [+] to double a
number. The following is incorrect:
<CENTER><P>
<IMG src="fig3.5.png" ALT="incorrect inlet connection">
</P></CENTER>
<P> Here, I connected the left inlet before connecting the right hand one (although
this is not evident in the appearance of the patch.) The [+] thus adds the
new input (at left) to the previous input (at right).
<P> The [trigger] object, abbreviated [t], can be used to split out connections
from a single outlet in a determinate order. By convention, all objects in Pd,
when sending messages out more than one outlet, do so from right to left. If
you connect these to inlets of a second object without crossing wires, the
second object will get its leftmost inlet last, which is usually what you
want. Here is how to use [trigger] to disambiguate the previous example:
<CENTER><P>
<IMG src="fig3.6.png" ALT="trigger to disambiguate">
</P></CENTER>
<P> "Cold" (non-leftmost) inlets are almost universally used to store single
values (either numbers or symbols.) With the exception of [line], [line~]
and [vline~], these values are "sticky," i.e., once you set the value it is
good until the next time you set it. (The "line family" exception is for
sanity's sake.)
<P> One more question sometimes comes up in execution order, which is
the order in which two messages are sent to a single "cold" inlet. In this
situation, since the messages are merged, the last value to be received is
the value that is used in the computation.
<H3> <A id="s4.4"> 2.4.4. Message boxes </A> </H3>
<p>Message boxes are text boxes in which you type a message. When the message
box is activated, either by clicking on it or sending something to its inlet,
the message or messages are sent, either to the message box's outlet or
elsewhere as specified.
<CENTER><P>
<IMG src="fig3.7.png" ALT="message boxes">
</P></CENTER>
<P>The first of the message boxes above contains the single number 1.5; this
message has an implicit selector of "float." The second is a list with three
numbers in it, and in the third, the selector is "my" and the two arguments are
the number 5 and the symbol "toes."
<P> Multiple messages may be separated by commas as shown:
<CENTER><P>
<IMG src="fig3.8.png" ALT="multiple messages in one box">
</P></CENTER>
<P>Here the three messages are the numbers 1, 2, and 3, and they are sent in
sequence (with no intervening time between them, as with the [trigger] object,
and having depth-first consequences so that whatever chain of actions depending
on "1" takes place before anything depending on "2" and so on.)
<P> Semicolons may also separate messages. A message following a semicolon must
specify a symbol giving a destination (in other words, semicolons are like commas
except that they clear the "current destination" so that the next message specifies
a new one). The "current destination" is at first the message box's own outlet. In
the example below, the leading semicolon immediately redirects messages from the
outlet to an object named "fred" (which is here a receive object), and likewise the
next message is sent to "sue."
<CENTER><P>
<IMG src="fig3.9.png" ALT="semicolons to send messages">
</P></CENTER>
<P>Certain other objects (Pd windows, for example, and arrays) have Pd names as
destination symbols so you can send them messages this way. Also, the special object
"pd" is defined to which you may send messages to start and stop DSP and more.
<P> You can put variables in message boxes as shown below:
<CENTER><P>
<IMG src="fig3.10.png" ALT="variables in message boxes">
</P></CENTER>
<P>Here, "$1", etc., refer to the arguments of the arriving message (and aren't
defined if you send a "bang" message or if you click on the message box to
activate it.) Dollar sign variables are either numbers or symbols depending
on the incoming message; if symbols, you may even use them to specify variable
message selectors or destinations.
<H3> <A id="s5"> 2.5. Audio signals </A> </H3>
<P>
Using Pd you can build audio patches which can synthesize musical sounds,
analyze incoming sounds, process incoming sounds to produce transformed
audio outputs, or integrate audio processing with other media. This section
describes how Pd treats audio signals.
<H3> <A id="s5.1"> 2.5.1. Sample rate and format </A> </H3>
<P>
Pd's audio signals are internally kept as 32-bit floating point numbers, so
you have all the dynamic range you could want. However, depending on your
hardware, audio I/O is usually limited to 16 or 24 bits. Inputs all appear
between the values of -1 and 1; and output values will be clipped to that range.
Pd assumes a sample rate of 44100 unless you override this (
in Pd's command line or in the "audio setup" dialog).
<P> Pd can read or write samples to files either in 16-bit or 24-bit fixed point
or in 32-bit floating point, in 'wave', 'aiff', 'caf', and 'next' formats via
the [soundfiler], [readsf~], and [writesf~] objects.
<H3> <A id="s5.2"> 2.5.2. Tilde objects and audio connections </A> </H3>
<P>Audio computations in Pd are carried out by "tilde objects" such as [osc~]
whose names conventionally end in a tilde character, which resembles a sinusoid
warnd you what they deal with audio signals. Tilde objects can intercommunicate
via audio connections. When audio computation is turned on, or when you change
the audio network while audio is on, Pd sorts all the tilde objects into a linear
order for running; then this linear list is run down in blocks of 64 samples each;
at 44100 Hz. this means the audio network runs every 1.45 milliseconds.
<P> Inlets or outlets are configured in Pd either for messages or audio; you can't
connect an audio outlet to a non-audio inlet. An object's leftmost inlet may accept
both audio and messages; any other inlet is either one or the other, but secondary
audio inlets take floats at control data and promote them automatically to signals.
Nonethwless, in some cases, the inlet may take both a float or a sinal and run
different algorithms in each case. One example is [lop~], which runs a more
efficient routine if no signals are connected to the right inlet. The [+~], [-~],
[*~], [/~]. [max~], [min~], [log~] and [pow~] objects can be configured to take
control or signal inputs in their 2nd inlet depending on the creation argument.
<P> The audio network, that is, the tilde objects and their interconnections,
must be acyclic. If there are loops, at "sort time", you will see an error
message on the main Pd window that says <b>"DSP loop detected (some tilde
objects weren't scheduled)"</b>. You can build algorithms with feedback using
nonlocal signal connections as explained in the 2.5.5. subsection.
<P> Your subpatches can have audio inlets and outlets via the [inlet~] and [outlet~]
objects (see <A href="x2.htm#s8"> Subpatches </A>).
<H3> <A id=s5.3> 2.5.3. Converting audio to and from messages </A> </H3>
<P> If you want to use a control value as a signal, you can use the [sig~]
object to convert it. This is usually rare since objects usually promote
floats to signals as mentioned. At least this is true for all native objects
in Pd, but there are externals that can behave differently. The [sig~] object
is also useful for loading a default signal value with its creation argument.
You can also use [line~] and [vline~] to "convert" from control to signal with
a smoothen ramp, so to speak, which can be quite useful.
<P> The other direction, signal to control, requires that you specify at what
moments you want the signal sampled. This is handled by the [snapshot~] object,
but you can also sample a signal with [tabwrite~] and then get access it via
[tabread] or [tabread4] (note the missing tildes!). There are also analysis
objects, the simplest of which is [env~], the envelope follower, that outputs
control data floats.
<H3> <A id=s5.4> 2.5.4. Switching and blocking </A> </H3>
<P>You can use the [switch~] or [block~] objects to turn portions of your audio
computation on and off and to control the block size of computation. There may
be only one [switch~] or [block~] object in any window; it acts on the entire
window and all of its subwindows, which may still have their own nested
[switch~]/[block~] objects. Both [s]witch~] and [block~] take a block size
and an overlap factor as arguments; so for instance, [block~ 1024 4] specifies
1024 sample blocks, overlapped by a factor of 4 relative to the parent window.
The [switch~] version carries a small computational overhead in addition to
whatever overhead is associated with changing the block size.
<P> Larger block sizes than 64 should result in small increases in run-time
efficiency. Also, the [fft~] and related objects operate on blocks so that
setting the block size also sets the number of FFT channels. You may wish
to use block sizes smaller than 64 to gain finer resolutions of message/audio
interaction, or to reduce "block delay" in feedback algorithms. At the extreme,
setting the block size to 1 allows you to write your own recursive filters or
other DSP algorithms that require a one sample feedcback.
<P> You can use [switch~] to budget your DSP computations; for instance you might
want to be able to switch between two synthesis algorithms. To do this, put
each algorithm in its own subpatch (which can have sub-sub patches in turn, for
a voice bank for instance), and switch each one off as you switch the other one
on. Beware of clicks; if you have a [line~] controlling output level, give it
time to ramp to zero before you switch it off or it will be stuck at a nonzero
value for the next time it comes back on.
<P> When a subpatch is switched off its audio outputs generate zeros; this