HelpSource/Classes/SynthDesc.schelp

   1 class:: SynthDesc
   2 summary:: Description of a synth definition
   3 categories:: Server>Nodes
   4 related:: Classes/SynthDef, Classes/Synth
   5
   6 description::
   7 Contains a description of a link::Classes/SynthDef::, including its name, control names and default values.
   8 Information is also stored on its outputs and inputs and whether it has a gate control.
   9
  10 SynthDescs are needed by the event stream system, so when using link::Classes/Pbind::, the instruments' default parameters are derived from the SynthDesc.
  11
  12 subsection:: Creation
  13 SynthDescs are created by link::Classes/SynthDescLib::, by reading a compiled synth def file.
  14 code::
  15 SynthDescLib.global.read("synthdefs/default.scsyndef");
  16 SynthDescLib.global.synthDescs.at(\default)
  17 SynthDescLib.global.at(\default) // shortcut, same as line above
  18 ::
  19
  20 code::aSynthDef.store:: and code::aSynthDef.add:: also create a synthDesc in the global library.
  21 definitionlist::
  22 ## .store || saves a synthdef file on disk (like .load);
  23 ## .add || creates the synthDesc wholly in memory and sends the synthdef to registered servers.
  24 ::
  25 code::
  26 (
  27 SynthDef("test", { arg out, freq, xFade;
  28         XOut.ar(out, xFade, SinOsc.ar(freq))
  29 }).store
  30 );
  31 ::
  32
  33 Browse the properties of SynthDescs:
  34 code::
  35 SynthDescLib.global.browse;
  36 ::
  37
  38 section:: SynthDescs and SynthDef metadata
  39
  40 Metadata associated with a link::Classes/SynthDef:: consists of an link::Classes/Event:: (a syntactically shorter form of an identity dictionary) containing information about the SynthDef that is useful to the client, and which cannot be inferred from the binary .scsyndef stream.
  41
  42 For example, by listing argument names and link::Classes/ControlSpec::s under the 'specs' key in the event, the client can use the specs to build a link::Classes/GUI:: allowing control over all the SynthDef's inputs, with sensible range mappings. (The "window" button in the SynthDescLib browser does exactly this -- any ControlSpecs listed in the metadata will be used for the corresponding synth input's slider.)
  43
  44 Currently only the 'specs' key is reserved. Other keys may be used as needed for specific applications. As the use of SynthDef metadata evolves, other keys may be standardized.
  45
  46 subsection:: Creation and access
  47 Metadata are specified when creating a link::Classes/SynthDef::. If the SynthDef is .store'd (or .added'd) into a SynthDescLib, the metadata become part of the SynthDesc as well. Thereafter, the metadata can be accessed through SynthDescLib:
  48 code::
  49 SynthDescLib.global[\synthDefName].metadata
  50 ::
  51
  52 subsection:: Persistence and metadata plug-ins
  53 Storing a SynthDef into the library with .store persists the SynthDef on disk. Metadata may also be persisted at the same time by using the appropriate metadata plug-in class. The plug-in is responsible for writing a separate metadata file into the synthdefs directory, and reading the file back at the same time that a SynthDesc is created for a .scsyndef file using SynthDesc.read or SynthDescLib.global.read.
  54
  55 The currently available plug-ins are:
  56 definitionlist::
  57 ## AbstractMDPlugin || A dummy plug-in, which writes no metadata. This is the default, so that users who are not interested in metadata will not find extra files in the synthdefs directory.
  58 ## TextArchiveMDPlugin || Writes the metadata as a SuperCollider text archive -- metadata.writeArchive(path).
  59 ::
  60 Other plug-ins may be written at a later date, to support sharing metadata with applications in other languages using formats like JSON (JavaScript Object Notation) or XML.
  61
  62 You may specify a global default metadata plug-in as follows:
  63 code::
  64 SynthDesc.mdPlugin = ... plug-in class name ...;
  65 ::
  66 Metadata are not written when using code::SynthDef().load(server)::. This is because SynthDesc exists to describe a SynthDef to the client, whereas SynthDef is really just an abstraction to create a link::Classes/UGen:: graph for the server.
  67
  68 subsection:: Automatic population
  69 You may write a function to populate entries into the metadata automatically, based on the SynthDesc object. This function executes when reading a SynthDesc from disk, when using .add, and before writing a metadata file (in .store).
  70 code::
  71 SynthDesc.populateMetadataFunc = { |synthdesc|
  72         ... do work here ...
  73 };
  74 ::
  75
  76 subsection:: Synchronization
  77 Whenever a .scsyndef file is written, any existing metadata files will be deleted so that a new .scsyndef file will not exist on disk with out-of-date metadata.
  78
  79 subsection:: Reading
  80 When reading a SynthDesc, metadata files will be checked and one will be read, regardless of format. (Even if the default SynthDesc.mdPlugin is different from the file format on disk, the disk file will be read using the appropriate plug-in anyway.)
  81
  82 There should be only one metadata file at a time. However, in the case of conflicts, the default SynthDesc.mdPlugin will be preferred. The file extension identifies the format.
  83
  84 subsection:: Metadata Examples
  85 code::
  86 s.boot;
  87
  88 d = SynthDef(\mdDemo, { |out, freq, cutoff, volume, gate = 1|
  89         var     sig = LPF.ar(Saw.ar(freq, volume), cutoff),
  90                 env = EnvGen.kr(Env.adsr, gate, doneAction: 2);
  91         Out.ar(out, (sig * env) ! 2)
  92 }).add;
  93
  94 SynthDescLib.global[\mdDemo].makeWindow;
  95
  96 // Note in the resulting window that Freq has a slider, but Cutoff and Volume do not.
  97 // This is because there are no global specs for the argument names 'cutoff' and 'volume'.
  98
  99
 100 // Same SynthDef, but adding metadata
 101 // \freq and \amp exist in the global ControlSpec collection -- Spec.specs
 102 // They are converted to real ControlSpecs using .asSpec
 103
 104 d = SynthDef(\mdDemo, { |out, freq, cutoff, volume, gate = 1|
 105         var     sig = LPF.ar(Saw.ar(freq, volume), cutoff),
 106                 env = EnvGen.kr(Env.adsr, gate, doneAction: 2);
 107         Out.ar(out, (sig * env) ! 2)
 108 }, metadata: (specs: (cutoff: \freq, volume: \amp))).add;
 109
 110 SynthDescLib.global[\mdDemo].makeWindow;
 111
 112 // Now cutoff has a slider for frequency and volume has amplitude scaling
 113
 114
 115 // Store the SynthDef along with metadata
 116 d.store(mdPlugin: TextArchiveMDPlugin);
 117
 118 "ls %mdDemo.*".format(SynthDef.synthDefDir.escapeChar($ )).unixCmd;
 119
 120 // In addition to .scsyndef, there's also .txarcmeta - "text archive metadata"
 121
 122 // Load a fresh SynthDesc from disk for it
 123 // The SynthDesc.read interface is a bit weird - e will be a dictionary holding the SynthDesc
 124 e = SynthDesc.read(SynthDef.synthDefDir ++ "mdDemo.scsyndef");
 125
 126 // Metadata have been successfully read from disk!
 127 // You could even do the above after recompiling and the MD would be there
 128 e[\mdDemo].metadata
 129
 130 e[\mdDemo].makeWindow;
 131 ::
 132
 133 classmethods::
 134 private:: initClass
 135
 136 method:: read
 137 adds all synthDescs in a path to a dict
 138
 139 instancemethods::
 140
 141 method:: name
 142 returns:: the name of the SynthDef
 143
 144 method:: controls
 145 returns:: an array of instances of link::Classes/ControlName::, each of which
 146 have the following fields: name, index, rate, defaultValue
 147 discussion::
 148 code::
 149 SynthDescLib.global.at(\default).controlNames.postln;
 150 ::
 151
 152 method:: controlDict
 153 An link::Classes/IdentityDictionary:: of the link::Classes/ControlName::'s, indexed by name.
 154 This can be used for fast lookup of control index by name, for example to set a specific element of a multichannel control.
 155
 156 method:: controlNames
 157 returns:: an array of Strings with the names of controls
 158
 159 method:: outputs
 160 returns:: an array of link::Classes/IODesc:: that describes the available outputs.
 161 method:: inputs
 162 returns:: an array of link::Classes/IODesc:: that describes the available inputs.
 163
 164 method:: hasGate
 165 is true if the Synthdef has a gate input
 166
 167 method:: canFreeSynth
 168 is true if the link::Classes/Synth:: can free itself (via some means, usually a doneAction)
 169 discussion::
 170 This can be used to decide if to remove a Synth directly via free-message.
 171 code::
 172 SynthDescLib.global.at(\default).canFreeSynth;
 173 ::
 174
 175 method:: msgFunc
 176 the function which is used to create an array of arguments for
 177 playing a synth def in patterns
 178 discussion::
 179 code::
 180 SynthDescLib.global.synthDescs.at(\default).msgFunc.postcs;
 181 ::
 182