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 section:: Basic types
  10 All data is stored big endian. All data is packed, not padded or aligned.
  11 definitionlist::
  12 ## int32 || a 32 bit integer.
  13 ## int16 || a 16 bit integer.
  14 ## int8 || an 8 bit integer.
  15 ## float32 || a 32 bit IEEE floating point number.
  16 ## pstring || a pascal format string: a byte giving the length followed by that many bytes.
  17 ::
  18
  19 section:: File Format
  20
  21 a strong::synth-definition-file:: is :
  22 list::
  23 ## int32 - four byte file type id containing the ASCII characters: "SCgf"
  24 ## int32 - file version, currently 1.
  25 ## int16 - number of synth definitions in this file (D).
  26 ## [ strong::synth-definition:: ] * D
  27 ::
  28
  29 a strong::synth-definition:: is :
  30 list::
  31 ## pstring - the name of the synth definition
  32 ## int16 - number of constants (K)
  33 ## [float32] * K - constant values
  34 ## int16 - number of parameters (P)
  35 ## [float32] * P - initial parameter values
  36 ## int16 - number of parameter names (N)
  37 ## [ strong::param-name:: ] * N
  38 ## int16 - number of unit generators (U)
  39 ## [ strong::ugen-spec:: ] * U
  40 ::
  41
  42 a strong::param-name:: is :
  43 list::
  44 ## pstring - the name of the parameter
  45 ## int16 - its index in the parameter array
  46 ::
  47
  48 a strong::ugen-spec:: is :
  49 list::
  50 ## pstring - the name of the SC unit generator class
  51 ## int8 - calculation rate
  52 ## int16 - number of inputs (I)
  53 ## int16 - number of outputs (O)
  54 ## int16 - special index
  55 ## [ strong::input-spec:: ] * I
  56 ## [ strong::output-spec:: ] * O
  57 ::
  58
  59 an strong::input-spec:: is :
  60 list::
  61 ## int16 - index of unit generator or -1 for a constant
  62 ## if (unit generator index == -1) :
  63 list::
  64 ## int16 - index of constant
  65 ::
  66 ## else :
  67 list::
  68 ## int16 - index of unit generator output
  69 ::
  70 ::
  71
  72 an strong::output-spec:: is :
  73 list::
  74 ## int8 - calculation rate
  75 ::
  76
  77 section:: File Format as Tree
  78
  79 soft::added by Jonatan Liljedahl::
  80
  81 subsection::synth-definition-file
  82 tree::
  83 ## int32 - four byte file type id containing the ASCII characters: "SCgf"
  84 ## int32 - file version, currently 1.
  85 ## int16 - number of synth definitions in this file (D).
  86 ## [ strong::synth-definition:: ] * D
  87     tree::
  88     ## pstring - the name of the synth definition
  89     ## int16 - number of constants (K)
  90     ## [float32] * K - constant values
  91     ## int16 - number of parameters (P)
  92     ## [float32] * P - initial parameter values
  93     ## int16 - number of parameter names (N)
  94     ## [ strong::param-name:: ] * N
  95         tree::
  96         ## pstring - the name of the parameter
  97         ## int16 - its index in the parameter array
  98         ::
  99     ## int16 - number of unit generators (U)
 100     ## [ strong::ugen-spec:: ] * U
 101         tree::
 102         ## pstring - the name of the SC unit generator class
 103         ## int8 - calculation rate
 104         ## int16 - number of inputs (I)
 105         ## int16 - number of outputs (O)
 106         ## int16 - special index
 107         ## [ strong::input-spec:: ] * I
 108             tree::
 109             ## int16 - index of unit generator or -1 for a constant
 110             ## if (unit generator index == -1)
 111                 tree::
 112                 ## int16 - index of constant
 113                 ::
 114             ## else
 115                 tree::
 116                 ## int16 - index of unit generator output
 117                 ::
 118             ::
 119         ## [ strong::output-spec:: ] * O
 120             tree::
 121             ## int8 - calculation rate
 122             ::
 123         ::
 124     ::
 125 ::
 126
 127 section:: Glossary
 128
 129 definitionlist::
 130 ## calculation rate || the rate that a computation is done. There are three rates numbered 0, 1, 2 as follows:
 131 definitionlist::
 132 ## 0 = scalar rate || one sample is computed at initialization time only.
 133 ## 1 = control rate || one sample is computed each control period.
 134 ## 2 = audio rate || one sample is computed for each sample of audio output.
 135 ::
 136 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.
 137
 138 ## constant || a single floating point value that is used as a unit generator input.
 139
 140 ## parameter || a value that can be externally controlled using server commands /s.new, /n.set, /n.setn, /n.fill, /n.map .
 141
 142 ## 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.
 143
 144 ## 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.
 145
 146 ## synth || a collection of unit generators that execute together. A synth is a type of node.
 147
 148 ## synth definition || a specification for creating synths.
 149
 150 ## unit generator ||  a basic signal processing module with inputs and outputs. unit generators are connected together to form synths.
 151 ::
 152
 153 section:: Notes
 154
 155 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.
 156
 157 subsection:: For greatest efficiency:
 158
 159 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.
 160
 161 There should be no duplicate values in the constants table.
 162
 163 copyright © 2002 James McCartney - converted to new help system 2010 by Jonatan Liljedahl
 164