HelpSource/Classes/ServerOptions.schelp

   1 class:: ServerOptions
   2 summary:: Encapsulates commandline and other options for a Server
   3 categories:: Server
   4 related:: Classes/Server, Reference/Server-Architecture, Reference/Server-Command-Reference
   5
   6 description::
   7
   8 ServerOptions encapsulates various options for a server app within an object. This makes it convenient to launch multiple servers with the same options, or to archive different sets of options, etc.
   9 Every link::Classes/Server:: has an instance of ServerOptions created for it if one is not passed as the options argument when the Server object is created. (This is the case for example with the local and internal Servers which are created at startup.)
  10
  11 A Server's instance of ServerOptions is stored in its options instance variable, which can be accessed through corresponding getter and setter methods.
  12
  13 N.B. A ServerOptions' instance variables are translated into commandline arguments when a server app is booted. Thus a running Server must be rebooted before changes will take effect. There are also a few commandline options which are not currently encapsulated in ServerOptions. See link::Reference/Server-Architecture:: for more details.
  14
  15 ClassMethods::
  16 private:: prListDevices
  17
  18 method:: new
  19 Create and return a new instance of ServerOptions.
  20
  21 method:: devices
  22 Return an Array of Strings listing the audio devices currently available on the system.
  23
  24 method:: inDevices
  25 Return an Array of Strings listing the audio devices currently available on the system which have input channels.
  26
  27 method:: outDevices
  28 Return an Array of Strings listing the audio devices currently available on the system which have output channels.
  29
  30 instancemethods::
  31 subsection:: The Options
  32
  33 method:: blockSize
  34 The number of samples in one control period. The default is 64.
  35
  36 method:: device
  37 A String that allows you to choose a sound device to use as input and output. The default, nil will use the system's default input and output device(s) (more below in the examples).
  38
  39 note::When the server is compiled for jack natively, the teletype::device:: can be used to connect to a named server and
  40 use a specific client name. The argument specifies either a server name or a server name and the requested client
  41 name. Passing code::nil:: is equivalent to to teletype::default:SuperCollider::.
  42
  43 The jack connections can be configured via the environment variables teletype::SC_JACK_DEFAULT_INPUTS:: and
  44 teletype::SC_JACK_DEFAULT_OUTPUTS::. The format is either a string that specifies the another jack client or a
  45 comma-separate list of jack ports.
  46
  47 code::
  48 // connect first to input channels with system
  49 "SC_JACK_DEFAULT_INPUTS".setenv("system:capture_1,system:capture_2");
  50
  51 // connect all output channels with system
  52 "SC_JACK_DEFAULT_OUTPUTS".setenv("system");
  53 ::
  54
  55 ::
  56
  57 method:: inDevice
  58 A String that allows you to choose an input sound device. The default, nil will use the system's default input device (more below in the examples).
  59
  60 method:: outDevice
  61 A String that allows you to choose an output sound device. The default, nil will use the system's default output device (more below in the examples).
  62
  63 method:: hardwareBufferSize
  64 The preferred hardware buffer size. If non-nil the server app will attempt to set the hardware buffer frame size. Not all sizes are valid. See the documentation of your audio hardware for details. Default value is nil.
  65
  66 method:: initialNodeID
  67 By default, the Server object in the client begins allocating node IDs at 1000, reserving 0-999 for "permanent" nodes. You may change this default here.
  68
  69 method:: inputStreamsEnabled
  70 A String which allows turning off input streams that you are not interested in on the audio device. If the string is "01100", for example, then only the second and third input streams on the device will be enabled. Turning off streams can reduce CPU load. The default value is nil.
  71
  72 method:: loadDefs
  73 A Boolean indicating whether or not to load the synth definitions in synthdefs/ (or anywhere set in the environment variable SC_SYNTHDEF_PATH) at startup. The default is true.
  74
  75 method:: maxNodes
  76 The maximum number of nodes. The default is 1024.
  77
  78 method:: maxSynthDefs
  79 The maximum number of synthdefs. The default is 1024.
  80
  81 method:: memSize
  82 The number of kilobytes of real time memory allocated to the server. This memory is used to allocate synths and any memory that unit generators themselves allocate (for instance in the case of delay ugens which do not use buffers, such as CombN), and is separate from the memory used for buffers. Setting this too low is a common cause of 'exception in real time: alloc failed' errors. The default is 8192.
  83
  84 method:: numAudioBusChannels
  85 The number of audio rate busses, which includes input and output busses. The default is 128.
  86
  87 method:: numBuffers
  88 The number of global sample buffers available. (See Buffer.) The default is 1024.
  89
  90 method:: numControlBusChannels
  91 The number of internal control rate busses. The default is 4096.
  92
  93 method:: numInputBusChannels
  94 The number of audio input bus channels. This need not correspond to the number of hardware inputs. The default is 8.
  95
  96 method:: numOutputBusChannels
  97 The number of audio output bus channels. This need not correspond to the number of hardware outputs (this can be useful for instance in the case of recording). The default is 8.
  98
  99 method:: numRGens
 100 The number of seedable random number generators. The default is 64.
 101
 102 method:: numWireBufs
 103 The maximum number of buffers that are allocated to interconnect unit generators. (Not to be confused with the global sample buffers represented by Buffer.) This sets the limit of complexity of SynthDefs that can be loaded at runtime. This value will be automatically increased if a more complex def is loaded at startup, but it cannot be increased thereafter without rebooting. The default is 64.
 104
 105 method:: outputStreamsEnabled
 106 A String which allows turning off output streams that you are not interested in on the  audio device. If the string is "11000", for example, then only the first two output streams on the device will be enabled. Turning off streams can reduce CPU load.
 107
 108 method:: protocol
 109 A Symbol representing the communications protocol. Either code::\udp:: or code::\tcp::. The default is code::\udp::.
 110
 111 method:: remoteControlVolume
 112 A Boolean indicating whether this server should allow its volume to be set remotely. The default value is code::false::.
 113
 114 method:: sampleRate
 115 The preferred sample rate. If non-nil the server app will attempt to set the sample rate of the hardware. The hardware has to support the sample rate that you choose.
 116
 117 method:: verbosity
 118 Controls the verbosity of server messages. A value of 0 is normal behaviour, -1 suppresses informational messages, and -2 suppresses informational and many error messages. The default is 0.
 119
 120 method:: zeroConf
 121 A Boolean indication whether or not the server should publish its port using zero configuration networking, to facilitate network interaction. This is true by default; if you find unacceptable delays (beachballing) upon server boot, you can try setting this to false.
 122
 123 method:: restrictedPath
 124 Allows you to restrict the system paths in which scsynth is allowed to read/write files during running. A nil value (the default) means no restriction. Otherwise, set it as a string representing a single path.
 125
 126 method:: threads
 127 Number of audio threads that are spawned by supernova. For scsynth this value is ignored. If it is code::nil::or 0, it
 128 uses the one thread per CPU. Default is code::nil::.
 129
 130 method:: memoryLocking
 131 A Boolean indicating whether the server should try to lock its memory into physical RAM. Default is code::false::.
 132
 133
 134 subsection:: Other Instance Methods
 135 method:: asOptionsString
 136 Returns:: a String specifying the options in the format required by the command-line scsynth app.
 137 argument:: port
 138 The port number for the resulting server app. Default value is 57110.
 139
 140 method:: firstPrivateBus
 141 Returns:: the index of the first audio bus on this server which is not used by the input and output hardware.
 142
 143
 144 Examples::
 145 code::
 146 // Get the local server's options
 147
 148 o = Server.local.options;
 149
 150 // Post the number of output channels
 151
 152 o.numOutputBusChannels.postln;
 153
 154 // Set them to a new number
 155
 156 o.numOutputBusChannels = 6; // The next time it boots, this will take effect
 157
 158 // specify a device
 159
 160 o.device ="MOTU Traveler";      // use a specific soundcard
 161 o.device = nil;                 // use the system default soundcard
 162
 163 // Create a new instance of ServerOptions
 164
 165 o = ServerOptions.new;
 166
 167 // Set the memory size to twice the default
 168
 169 o.memSize = 4096;
 170
 171 // Create a new Server on the local machine using o for its options
 172
 173 t = Server(\Local2, NetAddr("127.0.0.1", 57111), o);
 174 t.makeWindow;
 175 t.boot;
 176 t.quit;
 177 ::
 178