1class:: BusPlug 2summary:: a listener on a bus 3categories:: JITLib>NodeProxy, Live Coding 4related:: Classes/Bus, Classes/Monitor, Classes/InBus, Classes/NodeProxy, Classes/Ndef 5 6description:: 7A BusPlug is represents a listener on a private link::Classes/Bus:: that makes it easy to play back to multiple channels. It is mainly in use as a superclass of NodeProxy, but it can be used for general channel routings as well. Most methods are documented in the link::Classes/NodeProxy:: helpfile. 8 9code:: 10s.boot; 11z = Bus.control(s, 16); 12z.setn({ |i| (i * 5).nthPrime } ! 16 * 5 + 100); 13a = BusPlug.for(z); 14{ Splay.ar(SinOsc.ar(a.kr(3, MouseX.kr(0, 25)))) * 0.1 }.play; // selectively play 3 channel of the 16, modulate offset 15:: 16 17ClassMethods:: 18 19 20 21method::new 22Create a new (neutral) instance on the given server 23 24method::for 25Create an instance with a given link::Classes/Bus::. 26 27method::audio 28Create a new audio rate instance on the given server 29 30method::control 31Create a new audio rate instance on the given server 32 33method::defaultNumAudio 34Default number of channels when initializing in audio rate and no specific number is given (default: 2). 35 36method::defaultNumControl 37Default number of channels when initializing in control rate and no specific number is given (default: 1). 38 39method::defaultReshaping 40default reshaping behaviour for BusPlug and its sublass NodeProxy. See: link::#-reshaping:: 41 42InstanceMethods:: 43 44private::makeBusArg, prepareForProxySynthDef, wakeUpToBundle, playNToBundle, playToBundle, newMonitorToBundle, clock 45 46method::server 47Return the server that the BusPlug runs on. 48 49method::clear 50Free the bus, end the monitor 51 52 53subsection::Making copies 54 55method::copy 56copies the hidden internal state to make the new BusPlug independent of the old, running on a new link::Classes/Bus::. By design, the link::Classes/Monitor:: is copied, but is not running (use play to start it in the same configuration). If needed, you can also copy the link::Classes/Monitor:: only (see: link::Classes/NodeProxy#-copy::). 57 58method::copyState 59Copy the internal settings of one proxy into another. Old state is cleared, the bus is freed. 60 61argument::proxy 62The object whose internal state is being copied. 63 64 65method::reshaping 66Determines how to behave when link::#-initBus:: is called. 67Current options: 68list:: 69## teletype::nil:: Once initialized, keep the same bus - this is the default 70## teletype::\static:: Same as nil, but allows you to override the default in instances 71## teletype::\elastic:: On a change, shrink and grow according to need, replace bus. Monitoring is adjusted. 72## teletype::\expanding:: On a change, only grow according to need, replace bus. Monitoring is adjusted. 73:: 74 75subsection::In UGen graphs and Patterns 76 77method::ar, kr 78Return a link to numChannels of my output. If uninitialized, creates a matching bus. Normally, strong::ar defaults to stereo, kr to mono::. This can be set in the classvars: link::#*defaultNumAudio::, link::#*defaultNumControl:: 79 80For consistency, it always returns an array of signals when no numChannels are given. To make it a single ugen output, use code::cumChannels = 1:: . See also: link::Classes/InBus::. 81 82argument::numChannels 83Number of channels returned. If the receiver is neutral or reshaping is elastic, initialize it to this number. If this is more than the available channels, use the clip behaviour (below). If set to code::1::, it will return an instance of link::Classes/InBus::, otherwise an Array of one or more instances of InBus. 84 85argument::offset 86Channel offset when reading a bus that has more channels than numChannels, cross fading between adjacent channels. 87 88argument::clip 89If set to 'wrap', exceeding channels will wrap around, if set to 'clip', repeat the last one. 90 91 92method::asUGenInput 93Returns the appropriate output to read from the BusPlug bus (an link::Classes/InBus:: UGen) 94code:: 95b = BusPlug.new; 96{ Blip.ar(b + 5) }.play; 97b.bus.set(12); 98:: 99 100method::embedInStream 101Returns the map argument for the bus, if the bus has multiple channels, it will return an array of map args. 102code:: 103b = BusPlug.new; 104x = Pbind(\z, b).asStream; 105x.next(()); // returns the map argument for the bus 106b.defineBus(\audio, 3); 107x.next(()); // returns map arguments for the audio rate bus 108:: 109 110method::asControlInput 111Returns the map argument for the bus, just like link::#-embedInStream:: 112 113subsection::Monitoring and Routing 114 115method::isPlaying 116Returns true if server is running and bus not nil. link::Classes/NodeProxy:: this returns true if the group is playing. 117 118method::isMonitoring 119Returns true if monitor is playing 120 121method::play 122Play from a bus index with a number of channels to another index with a number of channels, within a link::Classes/Group:: (i.e. a target group or server). 123 124argument::out 125bus index 126 127argument::numChannels 128number of channels to output. If BusPlug is neutral or reshaping is elastic, initialize it to this number. If this is more than the available channels, wrap around. If this is not given, and reshaping is elastic, it will automatically expand. 129 130argument::group 131target link::Classes/Group:: or link::Classes/Server:: in which to play the monitor synths. 132 133argument::multi 134keep old playback links and add new one 135 136argument::vol 137overall volume at which to monitor 138 139argument::fadeTime 140fade in / fade out time 141 142argument:: addAction 143Where in the node tree to play the monitor synths 144 145 146 147 148method::playN 149Play back on non-contiguous channels. See: link::Classes/Monitor:: and link::Reference/playN:: 150 151argument::outs 152array of destination channels (or single value) 153 154 155argument::amps 156array of amplitudes for each channel (or single value) 157 158argument::ins 159array of source channel offsets within the bus (or single value) 160 161argument:: vol 162Overall volume (multiplied by amps) 163 164argument:: fadeTime 165array of fadeTimes (or single value) for fade in / fade out 166 167argument:: group 168target link::Classes/Group:: or link::Classes/Server:: in which to play the monitor synths. 169 170argument:: addAction 171Where in the node tree to play the monitor synths 172 173 174 175method::stop 176stop to play out public channels. 177 178argument::fadeTime 179decay time for this action 180 181argument::reset 182if set to true, reset all monitor state. Otherwise, the previous play arguments are kept. 183 184 185method::monitor 186returns the current monitor (see link::Classes/Monitor::) 187 188 189 190 191subsection::Bus changes 192These methods are a little numerous, because they are important for implementing link::Classes/NodeProxy:: behavior. Mostly the methods link::#-bus:: and link::#-initBus:: will be sufficient in normal use. 193 194note::The old bus is freed when a new bus is made.:: 195 196method::isNeutral 197Returns true if no bus has been initialized so far. 198 199method::bus 200Set or get the bus. If BusPlug monitor is playing, restart the monitor to adequately play back the new bus. 201 202method::setBus 203set the bus object by passing a link::Classes/Bus::. 204note::you have to stop and play explicitly:: 205 206method::defineBus 207make a new bus for the BusPlug with a given rate and number of channels. 208 209method::initBus 210Make a new bus only if necessary. This depends on the current bus and the link::#-reshaping:: mode. 211 212returns::Boolean (true if successful). 213 214 215 216 217 218 219Examples:: 220 221code:: 222// using as a control bus listener 223 224s.boot; 225z = Bus.control(s, 16); 226a = BusPlug.for(z); 227 228m = { Mix(SinOsc.ar(a.kr(16), 0, 0.1)) }.play; 229 230z.setn(Array.rand(16, 300, 320).put(16.rand, rrand(500, 1000))); 231z.setn(Array.rand(16, 300, 320).put(16.rand, rrand(500, 1000))); 232z.setn(Array.rand(16, 300, 320).put(16.rand, rrand(500, 1000))); 233 234m.free; 235 236 237m = { SinOsc.ar(a.kr(2, MouseX.kr(0, 19)), 0, 0.1) }.play; // modulate channel offset 238 239z.setn(Array.rand(16, 300, 1320).put(16.rand, rrand(500, 1000))); 240 241 242m.free; z.free; 243 244// using as a audio monitor 245 246p = BusPlug.audio(s,2); 247d = { Out.ar(p.index, PinkNoise.ar([0.1, 0.1])) }.play; 248 249 250p.play; // monitor whatever plays in p (the execution order does not matter) 251 252 253 254d.free; 255d = { Out.ar(p.index, PinkNoise.ar([0.1, 0.1])) }.play; 256 257p.stop; 258p.play; 259 260// also p can play to another bus: 261 262p.stop; 263p.play(12); 264 265// listen to that bus for a test: 266x = { InFeedback.ar(12,2) }.play; 267x.free; 268:: 269