The SuperCollider Help Book - Andrea Valle

2325 Pages·2007·4.79 MB·English

the
SuperCollider
\Help
"Book"
s
e
l
i
f
p
l
e
h
e
h
t
m
o
r
f
t
e
s
e
p
y
t
/
/
TheBeaverbroughtpaper,portfolio,pens,
Andinkinanunfailingsupplies:
Whilestrangecreepycreaturescameoutoftheirdens
Andwatchedthemwithwonderingeyes.
(L.Carroll,TheHuntingoftheSnark,FittheFifth,TheBeaver’sLesson)
ThisbookisacollectionofalltheSuperColliderhelpfilesavailableinthestandarddistribution. Ithasbeentypesetwith
CONTEXT, a TEX-based typesetting system for document preparation which allows high-quality automated typesetting
withnativePDFoutput. TheCONTEXTcodehasbeengeneratedbyTheCollidingChampollion,aPythonmodulewhich
analysesandtranslatestheSuperColliderhtmlhelpfiles. AsTheCollidingChampollionisinitsfirstversion,itisstill
veryexperimental: inparticular, syntaxcolorizingpresentssomebugsandsomefeaturesarelacking(e.g. sometimes
colorsaremisplacedandindentationismissing). Thesituationpartlydependsalsoonsources: thehtmlfilesreproduces
alltheerrorsofthertffilesfromwhichtheyaregenerated,andthesearereproducedagainintheCONTEXTfiles. More,
the original rtf documentation lacks structure and an explicit markup would be needed to achieve better results (the
bestexampleisThreadhelpfile). ThebooktriestoreproducetheoriginalhierarchyoftheHelpfolder. Asdepthin
theHelpsubfoldersischanging,thebookstructureisabitmessy. Ageneralcriteriumisthatiffilesareatthesame
leveloffolderstheyarealllistedbeforethefolders. Notethat:
1. ineachdocumenttheoriginalpathisindicatedintheheader
2. eachdocumenthasauniqueID
Other Meta-data and stylistic improvements are on the ToDo list. Japanese tutorial is missing. This work has been
possiblethankstothreeopen-sourceprojects.
• SuperCollider: http://supercollider.sourceforge.net/
• CONTEXT:http://www.pragma-ADE.com/
• Python: http://www.python.org
Pleasereportbugs,suggestions,cries&whispersto:
[email protected]
CompiledonJanuary16,2007.
AndreaValle
http://www.semiotiche.it/andrea/
1
1 3vs2 5
2 BinaryOps 27
3 Collections 69
4 Control 174
5 Core 238
5.1 Kernel 239
5.2 Miscellanea 276
6 Crucial 300
6.1 Constraints 301
6.2 Control 313
6.3 Editors 316
6.4 Gui 327
6.5 Instr 362
6.6 Introspection 406
6.7 Miscellanea 409
6.8 Patching 415
6.9 Players 421
1 Miscellanea 422
2 SFP 423
6.10 Sample 424
6.11 Scheduling 438
6.12 Sequencers 459
6.13 ServerTools 477
6.14 UncoupledUsefulThings 479
7 Files 517
8 Geometry 534
9 Getting-Started 543
10 GUI 608
11 Help-scripts 740
2
12 JITLib 755
12.1 Environments 756
12.2 Extras 765
12.3 Miscellanea 773
12.4 Networking 783
12.5 Nodeproxy 802
12.6 Patterns 834
12.7 Tutorials 889
12.8 Ugens 970
13 Language 974
14 Linux 1059
15 Mark_Polishook_tutorial 1066
15.1 Debugging 1067
15.2 First_steps 1079
15.3 Miscellanea 1090
15.4 Synthesis 1093
16 Math 1159
17 Miscellanea 1197
18 Networking 1300
19 OSX 1303
19.1 Miscellanea 1304
19.2 Objc 1316
20 Other_Topics 1321
21 Quarks 1364
22 Scheduling 1369
23 ServerArchitecture 1385
24 Streams 1500
3
25 UGens 1728
25.1 Analysis 1729
25.2 Chaos 1741
25.3 Control 1771
25.4 Controls 1811
25.5 Delays 1824
25.6 Envelopes 1862
25.7 FFT 1881
25.8 Filters 1944
25.9 InfoUGens 2003
25.10 InOut 2015
25.11 Miscellanea 2047
25.12 Noise 2117
25.13 Oscillators 2166
25.14 Panners 2227
25.15 PhysicalModels 2246
25.16 SynthControl 2254
25.17 Triggers 2258
26 UnaryOps 2289
4
1 3vs2
5
Where: Help→3vs2→Backwards-Compatibility
ID: 1
Backwards Compatibility
There are a number of classes and methods that have been added to allow for backwards
compatibility with SC2 code. The most notable of these is Synth.play, which is basically
a wrapper for Function.play.
{ SinOsc.ar(440, 0, 0.5) }.play; // creates an arbitrarily named SynthDef and a Synth to play it
Synth.play({ SinOsc.ar(440, 0, 0.5) }); // in SC3 just a wrapper for Function.play with fewer args
Both of these will create synth nodes on the default server. Note that neither requires
the use of an Out.ar ugen; they simply output to the first audio bus. One can however
add an Out to Function.play in order to specify.
Synth.play({ Out.ar(1, SinOsc.ar(440, 0, 0.5)) });
In general, one should be aware of this distinction when using this code. When copying
such code for reuse with other SC3 classes (for example in a reusable SynthDef), it will
usually be necessary to add an Out.ar. Although useful for quick testing these methods
are generally inferior to SynthDef.play, as the latter is more direct, requires no modifi-
cations for general reuse, has greater general flexibility and has slightly less overhead.
(Although this is insignificant in most cases, it could be relevant when large numbers of
defs or nodes are being created.)
Like SynthDef.play, Function.play returns a Synth object which can then be messaged,
etc. However, since Function.play creates an arbitrarily named SynthDef, one cannot
reuse the resulting def, at least not without reading its name from the post window, or
getting it from the Synth object.
//The following examples are functionally equivalent
x = { arg freq = 440; Out.ar(1, SinOsc.ar(freq, 0, 0.5)) }.play(fadeTime: 0);
x.set(\freq, 880); // you can set arguments
y = Synth.new(x.defName); // get the arbitrary defname from x
x.free;
y.free;
x = SynthDef("backcompat-sine", { arg freq = 440; Out.ar(1, SinOsc.ar(freq, 0, 0.5)) }).play;
x.set(\freq, 880);
y = Synth.new("backcompat-sine");
6
Where: Help→3vs2→Backwards-Compatibility
x.free;
y.free;
Function.play is in general superior to both its SC2 equivalent and Synth.play. It has
a number of significant features such as the ability to specify the output bus and fade
times as arguments. See the Function helpfile for a more in-depth discussion.
A number of other classes and methods have also been added to improve compatibility.
These are listed below. In general there are equivalent or better ways of doing the same
things in SC3.
Synth *play use Function.play or SynthDef.play
GetFileDialog use CocoaDialog
GetStringDialog
Synth *stop use Server.freeAll
Synth *isPlaying Server.numSynths (this will include non-running nodes)
Mix *ar *arFill use Mix *new and *fill
SimpleNumber.rgb
Rawarray.write
7
Where: Help→3vs2→ClientVsServer
ID: 2
Client versus Server Operations
Unlike in SC2 where language and synthesis were unified in a single application, SC3
divides its operations between a language application (the SuperCollider app on which
you double-clicked to startup SC) and a synthesis-server application (a UNIX command-
line application called scsynth, which is started when you press the boot button on the
’local’ server window that is created by default at startup, or when you boot a Server
from code). The two applications communicate between each other through UDP or
TCP using a subset of CNMAT’s Open Sound Control.
This is a radical departure from the previous architecture (a more detailed discussion of
this and other matters can be found in the file sc3 intro 2 in the Examples folder) and
yields several important advantages:
The server can be controlled by programs other than the language app.
The language app can crash and synthesis will not stop.
The server can crash and the language will not.
The language and server apps can be running on different machines, even in different
parts of the world. This allows for efficient ’division of labour’ and network interactivity.
There is one notable drawback: The messaging process introduces a small amount of
latency. This should not be confused with audio latency which can be quite low. It only
means that there is a small, usually insignificant delay between the one side sending a
message and the other receiving it and acting upon it. (This can be minimized by using
the ’internal’ server. See Server for more detail.)
What is crucial to understand is the distinct functions of each side. The server app is
a lean and efficient program dedicated to audio functions. It knows nothing about SC
code, objects, OOP, or anything else to do with the SC language. It has (at least for
the moment) little programmatic ability.
When one creates a Synth object in the language app, that object is only the clientside
representation of a node on the server. The language app provides you with convienent
OOP functionality to keep track of and manipulate things on the server. All of this
functionality is possible to do ’by hand’ using the sendMsg method of Server, and other
similar messages. For instance:
s = Server.default;
8
Where: Help→3vs2→ClientVsServer
s.boot;
// this
n = s.nextNodeID;
s.sendMsg("/s_new", "default", n); // use the SynthDef "default"
s.sendMsg("/n_free", n);
// is equivalent to
x = Synth("default"); // create a synth on the default server (s) and allocate an ID for it
x.free; // free the synth, its ID and resources
The latter method gives you certain functionality. It gets a node ID for you automati-
cally, it allows you to control the Synth in syntactically elegant and efficient ways (see
the Synth and Node helpfiles), and to access all the advantages of object oriented
programming while doing so. Encapsulating the complexities and bookeeping greatly
reduces the chance of bugs in your own code.
It also has a small amount of overhead. It requires clientside CPU cycles and memory
to create and manipulate an object. Normally this is not significant, but there may be
times when you would prefer to use the less elegant, and less expensive first method, for
instance when creating large numbers of grains which will simply play and then deallo-
cate themselves.
Thus it is possible to create synth nodes on the server without actually creating Synth
objects, providing you are willing to do the required housekeeping yourself. The same is
true of group nodes, buffers, and buses. A more detailed discussion of these concepts
can be found in the NodeMessaging helpfile.
In conclusion, the crucial thing to remember is the distinction between things like nodes,
busses, buffers, and servers and the objects that represent them in the language app (i.e.
instances of Node, Bus, Buffer, and Server). Keeping these conceptually distinct will
help avoid much confusion.
9