Help/ServerArchitecture/Synth-Definition-File-Format.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <meta http-equiv="Content-Style-Type" content="text/css">
   6 <title></title>
   7 <meta name="Generator" content="Cocoa HTML Writer">
   8 <meta name="CocoaVersion" content="1038.25">
   9 <style type="text/css">
  10 p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px}
  11 p.p2 {margin: 0.0px 0.0px 0.0px 0.0px; font: 18.0px Helvetica}
  12 p.p3 {margin: 0.0px 0.0px 0.0px 0.0px; font: 10.0px Helvetica}
  13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica}
  14 p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 14.0px Helvetica}
  15 p.p6 {margin: 0.0px 0.0px 0.0px 0.0px; font: 14.0px Helvetica; min-height: 17.0px}
  16 span.Apple-tab-span {white-space:pre}
  17 </style>
  18 </head>
  19 <body>
  20 <p class="p1"><br></p>
  21 <p class="p2">SuperCollider 3 Synth Definition File Format</p>
  22 <p class="p1"><br></p>
  23 <p class="p3">copyright © 2002 James McCartney</p>
  24 <p class="p1"><br></p>
  25 <p class="p4">Synth definition files are read by the synth server and define collections of unit generators and their connections. These files are currently written by<span class="Apple-converted-space">  </span>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.</p>
  26 <p class="p1"><br></p>
  27 <p class="p5"><b>Basic types<span class="Apple-converted-space"> </span></b></p>
  28 <p class="p6"><br></p>
  29 <p class="p4"><span class="Apple-tab-span">     </span>All data is stored big endian. All data is packed, not padded or aligned.</p>
  30 <p class="p4"><span class="Apple-tab-span">     </span>an <b>int32</b> is a 32 bit integer.</p>
  31 <p class="p4"><span class="Apple-tab-span">     </span>an <b>int16</b> is a 16 bit integer.</p>
  32 <p class="p4"><span class="Apple-tab-span">     </span>an <b>int8</b> is an 8 bit integer.</p>
  33 <p class="p4"><span class="Apple-tab-span">     </span>a <b>float32</b> is a 32 bit IEEE floating point number.</p>
  34 <p class="p4"><span class="Apple-tab-span">     </span>a <b>pstring</b> is a pascal format string: a byte giving the length followed by<span class="Apple-converted-space"> </span></p>
  35 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>that many bytes.<span class="Apple-converted-space"> </span></p>
  36 <p class="p1"><span class="Apple-tab-span">     </span></p>
  37 <p class="p1"><span class="Apple-tab-span">     </span></p>
  38 <p class="p5"><b>File Format<span class="Apple-converted-space"> </span></b></p>
  39 <p class="p6"><br></p>
  40 <p class="p4">a <b>synth-definition-file</b> is :</p>
  41 <p class="p4"><span class="Apple-tab-span">     </span><b>int32</b> - four byte file type id containing the ASCII characters: "SCgf"</p>
  42 <p class="p4"><span class="Apple-tab-span">     </span><b>int32</b> - file version, currently 1.</p>
  43 <p class="p4"><span class="Apple-tab-span">     </span><b>int16</b> - number of synth definitions in this file (D).</p>
  44 <p class="p4"><span class="Apple-tab-span">     </span>[<b>synth-definition</b>] * D</p>
  45 <p class="p4">end</p>
  46 <p class="p1"><br></p>
  47 <p class="p4">a <b>synth-definition</b> is :</p>
  48 <p class="p4"><span class="Apple-tab-span">     </span><b>pstring</b> - the name of the synth definition</p>
  49 <p class="p1"><span class="Apple-tab-span">     </span></p>
  50 <p class="p4"><span class="Apple-tab-span">     </span><b>int16</b> - number of constants (K)</p>
  51 <p class="p4"><span class="Apple-tab-span">     </span>[<b>float32</b>] * K - constant values</p>
  52 <p class="p1"><span class="Apple-tab-span">     </span></p>
  53 <p class="p4"><span class="Apple-tab-span">     </span><b>int16</b> - number of parameters (P)</p>
  54 <p class="p4"><span class="Apple-tab-span">     </span>[<b>float32</b>] * P - initial parameter values</p>
  55 <p class="p1"><span class="Apple-tab-span">     </span></p>
  56 <p class="p4"><span class="Apple-tab-span">     </span><b>int16</b> - number of parameter names (N)</p>
  57 <p class="p4"><span class="Apple-tab-span">     </span>[<b>param-name</b>] * N</p>
  58 <p class="p1"><span class="Apple-tab-span">     </span></p>
  59 <p class="p4"><span class="Apple-tab-span">     </span><b>int16</b> - number of unit generators (U)</p>
  60 <p class="p4"><span class="Apple-tab-span">     </span>[<b>ugen-spec</b>] * U</p>
  61 <p class="p4">end</p>
  62 <p class="p1"><span class="Apple-tab-span">     </span></p>
  63 <p class="p4">a <b>param-name</b> is :</p>
  64 <p class="p4"><span class="Apple-tab-span">     </span><b>pstring</b> - the name of the parameter</p>
  65 <p class="p4"><span class="Apple-tab-span">     </span><b>int16</b> - its index in the parameter array</p>
  66 <p class="p4">end</p>
  67 <p class="p1"><br></p>
  68 <p class="p4">a <b>ugen-spec</b> is :</p>
  69 <p class="p4"><span class="Apple-tab-span">     </span><b>pstring</b> - the name of the SC unit generator class</p>
  70 <p class="p4"><span class="Apple-tab-span">     </span><b>int8</b> - calculation rate</p>
  71 <p class="p4"><span class="Apple-tab-span">     </span><b>int16</b> - number of inputs (I)</p>
  72 <p class="p4"><span class="Apple-tab-span">     </span><b>int16</b> - number of outputs (O)</p>
  73 <p class="p4"><span class="Apple-tab-span">     </span><b>int16</b> - special index</p>
  74 <p class="p4"><span class="Apple-tab-span">     </span>[<b>input-spec</b>] * I</p>
  75 <p class="p4"><span class="Apple-tab-span">     </span>[<b>output-spec</b>] * O</p>
  76 <p class="p4">end</p>
  77 <p class="p1"><br></p>
  78 <p class="p4">an <b>input-spec</b> is :</p>
  79 <p class="p4"><span class="Apple-tab-span">     </span><b>int16</b> - index of unit generator or -1 for a constant</p>
  80 <p class="p4"><span class="Apple-tab-span">     </span>if (unit generator index == -1) {</p>
  81 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><b>int16</b> - index of constant</p>
  82 <p class="p4"><span class="Apple-tab-span">     </span>} else {</p>
  83 <p class="p4"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><b>int16</b> - index of unit generator output</p>
  84 <p class="p4"><span class="Apple-tab-span">     </span>}</p>
  85 <p class="p4">end</p>
  86 <p class="p1"><br></p>
  87 <p class="p4">an <b>output-spec</b> is :</p>
  88 <p class="p4"><span class="Apple-tab-span">     </span><b>int8</b> - calculation rate</p>
  89 <p class="p4">end</p>
  90 <p class="p1"><br></p>
  91 <p class="p1"><br></p>
  92 <p class="p5"><b>Glossary</b></p>
  93 <p class="p1"><br></p>
  94 <p class="p4"><b>calculation rate</b> - the rate that a computation is done. There are three rates numbered 0, 1, 2 as follows:<span class="Apple-converted-space"> </span></p>
  95 <p class="p4"><b><span class="Apple-tab-span">  </span>0 = scalar rate</b> - one sample is computed at initialization time only.<span class="Apple-tab-span">   </span><b>1 = control rate</b> - one sample is computed each control period.</p>
  96 <p class="p4"><span class="Apple-tab-span">     </span><b>2 = audio rate</b> - one sample is computed for each sample of audio output.</p>
  97 <p class="p4">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.</p>
  98 <p class="p1"><br></p>
  99 <p class="p4"><b>constant</b> -<span class="Apple-converted-space">  </span>a single floating point value that is used as a unit generator input.</p>
 100 <p class="p1"><br></p>
 101 <p class="p4"><b>parameter</b> - a value that can be externally controlled using server commands /s.new, /n.set, /n.setn, /n.fill, /n.map .</p>
 102 <p class="p1"><br></p>
 103 <p class="p4"><b>parameter name</b> - 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<span class="Apple-converted-space">  </span>even though they exist at different offsets in their respective parameter arrays.</p>
 104 <p class="p1"><br></p>
 105 <p class="p4"><b>special index</b> - 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.</p>
 106 <p class="p1"><br></p>
 107 <p class="p4"><b>synth</b> - a collection of unit generators that execute together. A synth is a type of node.</p>
 108 <p class="p1"><br></p>
 109 <p class="p4"><b>synth definition</b> - a specification for creating synths.</p>
 110 <p class="p1"><br></p>
 111 <p class="p4"><b>unit generator</b> -<span class="Apple-converted-space">  </span>a basic signal processing module with inputs and outputs. unit generators are connected together to form synths.</p>
 112 <p class="p1"><br></p>
 113 <p class="p5"><b>Notes</b></p>
 114 <p class="p1"><br></p>
 115 <p class="p4">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.<span class="Apple-converted-space"> </span></p>
 116 <p class="p1"><br></p>
 117 <p class="p4"><b>For greatest efficiency:</b></p>
 118 <p class="p1"><br></p>
 119 <p class="p4">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.</p>
 120 <p class="p1"><br></p>
 121 <p class="p4">There should be no duplicate values in the constants table.</p>
 122 <p class="p1"><br></p>
 123 <p class="p3">copyright © 2002 James McCartney</p>
 124 </body>
 125 </html>