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
|
title:: Synth Definition File Format
summary:: Description of Synth Definition file format used by SC synth server
categories:: Server>Architecture
related:: Classes/SynthDef
Synth definition files are read by the synth server and define collections of unit generators and their connections. These files are currently written by the SuperCollider language application, but theoretically could be written by any program.
Such a program would need knowledge of the SC unit generators and their characteristics, such as number of inputs and outputs and available calculation rates. The code to write these files is open and available in the SuperCollider language app.
In the current SuperCollider 3.6 development version, there are two versions of SynthDef:
list::
## strong::SynthDef:: - The original SynthDef file format, backward compatible with .scsyndef files saved using earlier versions of SuperCollider.
## strong::SynthDef2:: - A revised version that extends SynthDef's capacity.
::
This document describes SynthDef2's format. See link::#Original SynthDef format:: for the differences between SynthDef and SynthDef2.
section:: Basic types
All data is stored big endian. All integers, unless otherwise noted, are signed. All data is packed, not padded or aligned.
definitionlist::
## int32 || a 32 bit integer.
## int16 || a 16 bit integer.
## int8 || an 8 bit integer.
## float32 || a 32 bit IEEE floating point number.
## pstring || a pascal format string: a byte (an strong::unsigned:: int8) giving the length followed by that many bytes.
::
section:: File Format
a strong::synth-definition-file:: is :
list::
## int32 - four byte file type id containing the ASCII characters: "SCgf"
## int32 - file version, currently 2.
## int16 - number of synth definitions in this file (D).
## [ strong::synth-definition:: ] * D
::
a strong::synth-definition:: is :
list::
## pstring - the name of the synth definition
## int32 - number of constants (K)
## [float32] * K - constant values
## int32 - number of parameters (P)
## [float32] * P - initial parameter values
## int32 - number of parameter names (N)
## [ strong::param-name:: ] * N
## int32 - number of unit generators (U)
## [ strong::ugen-spec:: ] * U
## int16 - number of variants (V)
## [ strong::variant-spec:: ] * V
::
a strong::param-name:: is :
list::
## pstring - the name of the parameter
## int32 - its index in the parameter array
::
a strong::ugen-spec:: is :
list::
## pstring - the name of the SC unit generator class
## int8 - calculation rate
## int32 - number of inputs (I)
## int32 - number of outputs (O)
## int16 - special index
## [ strong::input-spec:: ] * I
## [ strong::output-spec:: ] * O
::
an strong::input-spec:: is :
list::
## int32 - index of unit generator or -1 for a constant
## if (unit generator index == -1) :
list::
## int32 - index of constant
::
## else :
list::
## int32 - index of unit generator output
::
::
an strong::output-spec:: is :
list::
## int8 - calculation rate
::
a strong::variant-spec:: is :
list::
## pstring - the name of the variant
## [float32] * P - variant initial parameter values
::
section:: File Format as Tree
soft::added by Jonatan Liljedahl::
subsection::synth-definition-file
tree::
## int32 - four byte file type id containing the ASCII characters: "SCgf"
## int32 - file version, currently 2.
## int16 - number of synth definitions in this file (D).
## [ strong::synth-definition:: ] * D
tree::
## pstring - the name of the synth definition
## int32 - number of constants (K)
## [float32] * K - constant values
## int32 - number of parameters (P)
## [float32] * P - initial parameter values
## int32 - number of parameter names (N)
## [ strong::param-name:: ] * N
tree::
## pstring - the name of the parameter
## int32 - its index in the parameter array
::
## int32 - number of unit generators (U)
## [ strong::ugen-spec:: ] * U
tree::
## pstring - the name of the SC unit generator class
## int8 - calculation rate
## int32 - number of inputs (I)
## int32 - number of outputs (O)
## int16 - special index
## [ strong::input-spec:: ] * I
tree::
## int32 - index of unit generator or -1 for a constant
## if (unit generator index == -1)
tree::
## int32 - index of constant
::
## else
tree::
## int32 - index of unit generator output
::
::
## [ strong::output-spec:: ] * O
tree::
## int8 - calculation rate
::
::
## int16 - number of variants (V)
## [ strong::variant-spec:: ] * V
tree::
## pstring - the name of the variant
## [float32] * P - variant initial parameter values
::
::
::
section:: Original SynthDef format
The original SynthDef format differs in that the following items are teletype::int16:: instead of teletype::int32::.
note:: The following list describes what has changed between SynthDef and SynthDef2. It is not a complete description of the original SynthDef file format. ::
list::
## int32 - file version, currently 1. (This is emphasis::2:: for the new format.)
## a strong::synth-definition:: is :
list::
## int16 - number of constants (K)
## int16 - number of parameters (P)
## int16 - number of parameter names (N)
## int16 - number of unit generators (U)
::
## a strong::param-name:: is :
list::
## int16 - its index in the parameter array
::
## a strong::ugen-spec:: is :
list::
## int16 - number of inputs (I)
## int16 - number of outputs (O)
::
## an strong::input-spec:: is :
list::
## int16 - index of unit generator or -1 for a constant
## int16 - index of constant
## int16 - index of unit generator output
::
::
section:: Glossary
definitionlist::
## calculation rate || the rate that a computation is done. There are three rates numbered 0, 1, 2 as follows:
definitionlist::
## 0 = scalar rate || one sample is computed at initialization time only.
## 1 = control rate || one sample is computed each control period.
## 2 = audio rate || one sample is computed for each sample of audio output.
::
Outputs have their own calculation rate. This allows MultiOutUGens to have outputs at different rates. A one output unit generator's calculation rate should match that of its output.
## constant || a single floating point value that is used as a unit generator input.
## parameter || a value that can be externally controlled using server commands /s.new, /n.set, /n.setn, /n.fill, /n.map .
## parameter name || a string naming an index in the parameter array. This allows one to refer to the same semantic value such as 'freq' or 'pan' in different synths even though they exist at different offsets in their respective parameter arrays.
## special index || this value is used by some unit generators for a special purpose. For example, UnaryOpUGen and BinaryOpUGen use it to indicate which operator to perform. If not used it should be set to zero.
## synth || a collection of unit generators that execute together. A synth is a type of node.
## synth definition || a specification for creating synths.
## unit generator || a basic signal processing module with inputs and outputs. unit generators are connected together to form synths.
::
section:: Notes
Unit generators are listed in the order they will be executed. Inputs must refer to constants or previous unit generators. No feedback loops are allowed. Feedback must be accomplished via delay lines or through buses.
subsection:: For greatest efficiency:
Unit generators should be listed in an order that permits efficient reuse of connection buffers, which means that a depth first topological sort of the graph is preferable to breadth first.
There should be no duplicate values in the constants table.
copyright © 2002 James McCartney - converted to new help system 2010 by Jonatan Liljedahl, updated for version 2 by Scott Wilson 2011
|
