Product SiteDocumentation Site

11.3.11.3. Bus Objects

As SynthDef and Synth represent things stored on the server, the interpreter provides us with an instantiable "Bus" Class that represents the server's busses. In many programs that you write, you won't need to use a Bus Object - particularly when you're doing simple input and output with the automatically-reserved bus numbers. But, like the SynthDef and Synth Classes make it easier to deal with synthdefs and synths on the server (which are very difficult to deal with directly), the Bus Class makes it easier to deal with busses on the server, and provides some extra functionality to boot!
The primary advantage of using Bus Objects is that you don't have to keep track of bus numbers, whether they're being used, and how mnany channels are being routed. For simple input and output of audio-rate signals, you're better off simply remembering the bus numbers
The new message creates a new Bus object. This is the syntax:

Bus.audio(serverName, numberOfChannels);

or

Bus.control(serverName, numberOfChannels);

The interpreter takes "numberOfChannels" busses on the "serverName" server, and groups them together for multi-channel use in one Bus Object, which it returns to you. The "numberOfChannels" argument is optional; if you leave it out, the Bus Object will have only one bus, for single-channel signals. You should always assign the object to a variable, or else you have no way to use the bus later:
var myBus = Bus.audio( s, 2 );
The interpreter also keeps track of which bus numbers are used for which Bus Objects, so the signals will never get confused. Of course, you can still route signals through those bus numbers without using the Bus Object, but the Bus Class helps us to keep things straight.
The following messages/functions can also be used with Bus Objects:
Table 11.5. Some Functions of the Bus Class
Message/Function Example Return Value
index b.index; The lowest bus number used by this Bus object.
numChannels b.numChannels; The number of busses used by this Bus object.
rate b.rate; Either audio or control.
server b.server; The name of the server used by the Bus object. The default server is localhost

When you are done with a Bus, you can release the channels for use by other Bus Objects:
<replaceable>myBusVariable</replaceable>.free;
<replaceable>myBusVariable</replaceable> = nil;
Like when sending the "free" message to a Synth Object, you should set the variable name of a "free'd" Bus to "nil". This will prevent you from accidentally sending audio there after the Bus is released.