HelpSource/Reference/Synth-Definition-File-Format.schelp

   1 title:: Synth Definition File Format
   2 summary:: Description of Synth Definition file format used by SC synth server
   3 categories:: Server>Architecture
   4 related:: Classes/SynthDef
   5
   6 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.
   7 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.
   8
   9 In the current SuperCollider 3.6 development version, there are two versions of SynthDef:
  10
  11 list::
  12 ## strong::SynthDef:: - The original SynthDef file format, backward compatible with .scsyndef files saved using earlier versions of SuperCollider.
  13 ## strong::SynthDef2:: - A revised version that extends SynthDef's capacity.
  14 ::
  15
  16 This document describes SynthDef2's format. See link::#original_synthdef_format#Original SynthDef format:: for the differences between SynthDef and SynthDef2.
  17
  18 section:: Basic types
  19 All data is stored big endian. All data is packed, not padded or aligned.
  20 definitionlist::
  21 ## int32 || a 32 bit integer.
  22 ## int16 || a 16 bit integer.
  23 ## int8 || an 8 bit integer.
  24 ## float32 || a 32 bit IEEE floating point number.
  25 ## pstring || a pascal format string: a byte giving the length followed by that many bytes.
  26 ::
  27
  28 section:: File Format
  29
  30 a strong::synth-definition-file:: is :
  31 list::
  32 ## int32 - four byte file type id containing the ASCII characters: "SCgf"
  33 ## int32 - file version, currently 2.
  34 ## int16 - number of synth definitions in this file (D).
  35 ## [ strong::synth-definition:: ] * D
  36 ::
  37
  38 a strong::synth-definition:: is :
  39 list::
  40 ## pstring - the name of the synth definition
  41 ## int16 - number of constants (K)
  42 ## [float32] * K - constant values
  43 ## int16 - number of parameters (P)
  44 ## [float32] * P - initial parameter values
  45 ## int16 - number of parameter names (N)
  46 ## [ strong::param-name:: ] * N
  47 ## int16 - number of unit generators (U)
  48 ## [ strong::ugen-spec:: ] * U
  49 ## int16 - number of variants (V)
  50 ## [ strong::variant-spec:: ] * V
  51 ::
  52
  53 a strong::param-name:: is :
  54 list::
  55 ## pstring - the name of the parameter
  56 ## int16 - its index in the parameter array
  57 ::
  58
  59 a strong::ugen-spec:: is :
  60 list::
  61 ## pstring - the name of the SC unit generator class
  62 ## int8 - calculation rate
  63 ## int16 - number of inputs (I)
  64 ## int16 - number of outputs (O)
  65 ## int16 - special index
  66 ## [ strong::input-spec:: ] * I
  67 ## [ strong::output-spec:: ] * O
  68 ::
  69
  70 an strong::input-spec:: is :
  71 list::
  72 ## int16 - index of unit generator or -1 for a constant
  73 ## if (unit generator index == -1) :
  74 list::
  75 ## int16 - index of constant
  76 ::
  77 ## else :
  78 list::
  79 ## int16 - index of unit generator output
  80 ::
  81 ::
  82
  83 an strong::output-spec:: is :
  84 list::
  85 ## int8 - calculation rate
  86 ::
  87
  88 a strong::variant-spec:: is :
  89 list::
  90 ## pstring - the name of the variant
  91 ## [float32] * P - variant initial parameter values
  92 ::
  93
  94 section:: File Format as Tree
  95
  96 soft::added by Jonatan Liljedahl::
  97
  98 subsection::synth-definition-file
  99 tree::
 100 ## int32 - four byte file type id containing the ASCII characters: "SCgf"
 101 ## int32 - file version, currently 2.
 102 ## int16 - number of synth definitions in this file (D).
 103 ## [ strong::synth-definition:: ] * D
 104     tree::
 105     ## pstring - the name of the synth definition
 106     ## int16 - number of constants (K)
 107     ## [float32] * K - constant values
 108     ## int16 - number of parameters (P)
 109     ## [float32] * P - initial parameter values
 110     ## int16 - number of parameter names (N)
 111     ## [ strong::param-name:: ] * N
 112         tree::
 113         ## pstring - the name of the parameter
 114         ## int16 - its index in the parameter array
 115         ::
 116     ## int16 - number of unit generators (U)
 117     ## [ strong::ugen-spec:: ] * U
 118         tree::
 119         ## pstring - the name of the SC unit generator class
 120         ## int8 - calculation rate
 121         ## int16 - number of inputs (I)
 122         ## int16 - number of outputs (O)
 123         ## int16 - special index
 124         ## [ strong::input-spec:: ] * I
 125             tree::
 126             ## int16 - index of unit generator or -1 for a constant
 127             ## if (unit generator index == -1)
 128                 tree::
 129                 ## int16 - index of constant
 130                 ::
 131             ## else
 132                 tree::
 133                 ## int16 - index of unit generator output
 134                 ::
 135             ::
 136         ## [ strong::output-spec:: ] * O
 137             tree::
 138             ## int8 - calculation rate
 139             ::
 140         ::
 141     ## int16 - number of variants (V)
 142     ## [ strong::variant-spec:: ] * V
 143         tree::
 144         ## pstring - the name of the variant
 145         ## [float32] * P - variant initial parameter values
 146         ::
 147     ::
 148 ::
 149
 150 section:: Original SynthDef format
 151
 152 The original SynthDef format differs in that the following items are teletype::int16:: instead of teletype::int32::.
 153
 154 note:: The following list describes what has changed between SynthDef and SynthDef2. It is not a complete description of the the original SynthDef file format. ::
 155
 156 list::
 157 ## int32 - file version, currently 1. (This is emphasis::2:: for the new format.)
 158
 159 ## a strong::synth-definition:: is :
 160 list::
 161 ## int16 - number of constants (K)
 162 ## int16 - number of parameters (P)
 163 ## int16 - number of parameter names (N)
 164 ## int16 - number of unit generators (U)
 165 ::
 166 ## a strong::param-name:: is :
 167 list::
 168 ## int16 - its index in the parameter array
 169 ::
 170
 171 ## a strong::ugen-spec:: is :
 172 list::
 173 ## int16 - number of inputs (I)
 174 ## int16 - number of outputs (O)
 175 ::
 176
 177 ## an strong::input-spec:: is :
 178 list::
 179 ## int16 - index of unit generator or -1 for a constant
 180 ## int16 - index of constant
 181 ## int16 - index of unit generator output
 182 ::
 183 ::
 184
 185
 186 section:: Glossary
 187
 188 definitionlist::
 189 ## calculation rate || the rate that a computation is done. There are three rates numbered 0, 1, 2 as follows:
 190 definitionlist::
 191 ## 0 = scalar rate || one sample is computed at initialization time only.
 192 ## 1 = control rate || one sample is computed each control period.
 193 ## 2 = audio rate || one sample is computed for each sample of audio output.
 194 ::
 195 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.
 196
 197 ## constant || a single floating point value that is used as a unit generator input.
 198
 199 ## parameter || a value that can be externally controlled using server commands /s.new, /n.set, /n.setn, /n.fill, /n.map .
 200
 201 ## parameter name || a string naming an index in the 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.
 202
 203 ## 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.
 204
 205 ## synth || a collection of unit generators that execute together. A synth is a type of node.
 206
 207 ## synth definition || a specification for creating synths.
 208
 209 ## unit generator ||  a basic signal processing module with inputs and outputs. unit generators are connected together to form synths.
 210 ::
 211
 212 section:: Notes
 213
 214 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.
 215
 216 subsection:: For greatest efficiency:
 217
 218 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.
 219
 220 There should be no duplicate values in the constants table.
 221
 222 copyright © 2002 James McCartney - converted to new help system 2010 by Jonatan Liljedahl, updated for version 2 by Scott Wilson 2011
 223