NodeProxy:
Filter:
Classes | JITLib > NodeProxy | Live Coding

NodeProxy : BusPlug : AbstractFunction : Object

a reference on a server
Source: NodeProxy.sc
Subclasses: Ndef

Description

Generally a proxy is a placeholder for something. A node proxy is a placeholder for something playing on a server and writes to a limited number of busses (usually a synth, but also an event stream that makes synths). NodeProxy objects can be replaced and recombined while they play. Also they can be used to build a larger structure which is used and modified later on. Overview: JITLib.

NodeProxy is used internally in ProxySpace and it is a superclass of Ndef, allowing to easily access and combine a large number of placeholders.

Graphical editor for a node proxy: NdefGui.

NOTE: NodeProxy plays on a private bus. If you want to hear the output, use -play and -stop. To free inner players and stop listen: -end. Entirely removing all inner settings: -clear

Further reading

First Example

Class Methods

Creation

NodeProxy.new(server, rate, numChannels, inputs)

Return a new instance of NodeProxy.

Arguments:

server

The server on which to run and where the bus is allocated (default: Server.default)

rate

If given, proxy is initialized to this rate

numChannels

If given, proxy is initialized to this number of channels

inputs

If given, proxy is initialized with the given inputs as objects on subsequent slots.

NodeProxy.audio(server, numChannels)

From superclass: BusPlug

Create a new audio rate instance on the given server.

NodeProxy.control(server, numChannels)

From superclass: BusPlug

Create a new control rate instance on the given server.

NodeProxy.for(bus)

From superclass: BusPlug

Create an instance with a given Bus.

Accessing Class Variables

NodeProxy.defaultNumAudio

NodeProxy.defaultNumAudio = value

From superclass: BusPlug

Default number of channels when initializing in audio rate and no specific number is given (default: 2).

NodeProxy.defaultNumControl

NodeProxy.defaultNumControl = value

From superclass: BusPlug

Default number of channels when initializing in control rate and no specific number is given (default: 1).

NodeProxy.defaultFadeTime

The overlap time between successive source replacements which all instances have by default. Each instance has its own value which can be set via fadeTime_.

Inherited class methods

Instance Methods

Listening to the output

.play(out, numChannels, group, multi: false, vol, fadeTime, addAction)

From superclass: BusPlug

Play from a bus index with a number of channels to another index with a number of channels, within a Group (i.e. a target group or server).

Arguments:

out

bus index

numChannels

number 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.

group

target Group or Server in which to play the monitor synths.

multi

keep old playback links and add new one

vol

overall volume at which to monitor

fadeTime

fade in / fade out time

addAction

Where in the node tree to play the monitor synths

.playN(outs, amps, ins, vol, fadeTime, group, addAction)

From superclass: BusPlug

Play back on non-contiguous channels. See: Monitor and playN

Arguments:

outs

array of destination channels (or single value)

amps

array of amplitudes for each channel (or single value)

ins

array of source channel offsets within the bus (or single value)

vol

Overall volume (multiplied by amps)

fadeTime

array of fadeTimes (or single value) for fade in / fade out

group

target Group or Server in which to play the monitor synths.

addAction

Where in the node tree to play the monitor synths

.stop(fadeTime, reset: false)

From superclass: BusPlug

stop to play out public channels.

Arguments:

fadeTime

decay time for this action

reset

if set to true, reset all monitor state. Otherwise, the previous play arguments are kept.

.end(fadeTime, reset: false)

releases the synths and stops playback.

Arguments:

fadeTime

cross fade time for this action.

reset

if set to true, reset all monitor state. Otherwise, the previous play arguments are kept.

Embedding and Combining the proxy

.ar(numChannels, offset: 0, clip: 'wrap')

From superclass: BusPlug

.kr(numChannels, offset: 0, clip: 'wrap')

From superclass: BusPlug

Return a link to numChannels of my output. If uninitialized, creates a matching bus. Normally, ar defaults to stereo, kr to mono. This can be set in the classvars: *defaultNumAudio, *defaultNumControl

For consistency, it always returns an array of signals when no numChannels are given. To make it a single ugen output, use numChannels = 1 . See also: InBus.

Arguments:

numChannels

Number 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 1, it will return an instance of InBus, otherwise an Array of one or more instances of InBus.

offset

Channel offset when reading a bus that has more channels than numChannels, cross fading between adjacent channels.

clip

If set to 'wrap', exceeding channels will wrap around, if set to 'clip', repeat the last one.

<--(proxy)

Usage: proxyA <-- proxyB. Set proxyA source to proxyB and play proxyA. If proxyB was playing, fade it out. This is convenient in the following situation:

<<>(proxy, key: 'in')

Chaining. Usage: proxyA <<> proxyB <<> proxyC <<> ... . Map proxyC source to proxyB \in argument, and proxyB to proxyA's in argument.

<>>(proxy, key: 'in')

Inverse of the above. Usage: proxyA <>> proxyB <>> proxyC <>> ... .

Setting the source

NodeProxy keeps a number of slots which can be sources and are mixed on the same bus.. The default source is the slot 0. All objects can be exchanged while running, and also before and after. Normally, the source is active immediately. If sources are to be exchanged "quietly", set the node proxy to sleep (awake = false), or use the message prime().

See the list under section Supported sources

.source

.source = obj

Play a new synth through proxy and release/remove any old ones.

Arguments:

obj

can be one of the supported inputs (see Supported sources)

NOTE: When reshaping is set, e.g. to \elastic, setting the source can change the number of channels of the proxy. This means that its bus changes, and that child proxies, which read signals from it, may also change. See the example in Routing.

Routing

Signals can be routed between any number of node proxies.

See also: BusPlug: -ar, BusPlug: -value, Reshaping.

Here is a simple example, using Ndef (NodeProxy works similarly):

NOTE: If you don't specify the number of channels, an expression like Ndef.kr(\maus) will return an Array. Subsequently, e.g. by a Pan2 UGen, you may get the message:

WARNING: Synth output should be a flat array.

If you intend the output to be really mono, make it explicit by writing: Ndef.kr(\maus, 1)

With elastic reshaping, you can use the parent to expand the child, if you omit the number of channels in the routing:

Reserved parameters

Three parameters are automatically specified if they don't exist in a given UGen function. You can override their use: [\out, \gate, \fadeTime]

Specifying your own envelope

If a UGen function that is passed to the proxy has its own envelope, and if this envelope can free the synth, the node proxy uses this envelope instead of making its own. If you provide a fadeTime argument, the proxy's fadeTime will be used.

Making copies

.copy

copies the hidden internal state to make the new proxy independent of the old, but will keep the reference to the source object. The rendered SynthDef is cached, which makes this method more efficient than simply assigning the same function to a new proxy. By design, the monitor is copied, but is not running (use play to start it in the same configuration).

NOTE: If needed, you can also copy parts of a proxy, such as the Monitor (which usually routes the output back onto hardware busses) and the NodeMap, which keeps a mapping and setting scope.

.copyState(proxy)

Copy the internal settings of one proxy into another. Old state is cleared.

Arguments:

proxy

The proxy whose internal state is copied.

Reshaping

.reshaping

.reshaping = value

From superclass: BusPlug

Determines how to behave when a new source is added. Current options:

nilOnce initialized, keep the same bus - this is the default
\elasticOn a change, shrink and grow according to need, replace bus. The monitor and child proxies are adjusted.
\expandingOn a change, only grow according to need, replace bus. The monitor and child proxies are adjusted.

.mold(numChannels, rate, argReshaping, fadeTime)

Adjust the proxy to a given rate / numChannels. If there are any child proxies that have elastic -reshaping, they are adjusted accordingly.

Other ways to set or change the sources

.prime(obj)

Set source without starting the synth. To start it, -send can be used later. Running synths are released and proxy is initialized if still neutral.

.add(obj, channelOffset: 0, extraArgs, now: true)

Add a new source to the present ones

.removeAt(index, fadeTime)

Remove the object at index i and its synths, if they exist. If no index is supplied, remove them all.

.removeLast(fadeTime)

Remove the last object and its synths, if they exist.

.put(index, obj, channelOffset: 0, extraArgs, now: true)

Set the source by index. Objects can be inserted at any index, only the order of indices is relevant. Internally, NodeProxy uses an Order to access the sources.

Arguments:

index

where the object should be placed in the internal order. if -1, all objects are freed

obj

A valid source (see Supported sources).

channelOffset

using a multichannel setup it can be useful to set this, when the objects numChannels is smaller than the proxy

extraArgs

Arguments that can be sent with the object directly (not cached)

now

if set to false, only prepare the source and do not start the object (see -prime)

Controlling the running processes

.pause

Pause all objects and set proxy to paused

.resume

If paused, start all objects

.rebuild

Rebuild all SynthDefs from sources.

.orderNodes( ... proxies)

Arrange the order of groups from this to the last. This can be important when external input is filtered in order to minimize latency. Note that if a -parentGroup was provided, the nodes must be in the same parentGroup.

Release and cleaning up

.free(fadeTime, freeGroup: true)

Release all running synths and the group. If patterns are playing, stop them.

Arguments:

fadeTime

decay time for this action

freeGroup

a boolean

.release(fadeTime)

release running synths. If patterns are playing, stop them.

Arguments:

fadeTime

decay time for this action

.clear(fadeTime: 0)

reset everything to nil, neutralizes rate/numChannels

Arguments:

fadeTime

if a fadeTime is given, first fade out, then clear.

.schedAfterFade(func)

Calls a function after the fadeTime and server latency have passed. If the proxy specifies a quant value, the function is evaluated fadeTime + latency seconds after the next timepoint on the quant grid; otherwise, the fade delay begins immediately.

Arguments:

func

a function to be called at the appropriate time

Accessing Instance Variables

.sources

.sources = list

Returns an array of all sources

.source

.source = obj

Returns the first source.

.server

From superclass: BusPlug

The node proxy's server (a Server).

.bus

.bus = inBus

From superclass: BusPlug

The node proxy's private bus (a Bus). Because it has a private bus, it is not audible directly - monitoring it by (.play or playN) routes it to the hardware output channels.

.rate

From superclass: BusPlug

The bus rate (default: nil) The rate and number of channels is determined either when the instance is created (.control/.audio) or by lazy initialisation from the first source (see the_lazy_proxy)

.numChannels

From superclass: BusPlug

The bus numChannels (default: nil)

.isNeutral

From superclass: BusPlug

true if the proxy has no initialized bus.

.group

.group = inGroup

The node proxy's group (a Group). This is maintained by the proxy and serves as a context in which all synths are placed.

.parentGroup

.parentGroup = node

From superclass: BusPlug

Access the parentGroup (default: nil), which can be set to run the proxy's group in another group. This group has to be maintained (kept playing etc.) externally.

.clock

.clock = value

A clock, which can be set to account for different timing schemes, such as beat accurate replacement of sources.

.quant

.quant = value

A quant value, to specify quantizes replacement of sources. Compatible with the general use of quant in SuperCollider.

.quantize( ... proxies)

Synchronize the proxies by resending and adjusting to quant.

.monitor

.monitor = value

From superclass: BusPlug

Access the Monitor object, which plays back the output of the proxy's private bus.

.loaded

Returns true if the object has been initialized on the server, e.g. a synthDef has been stored.

.paused

Returns true if the processes are paused.

.awake

.awake = value

If set to false (default: true), a change of the source does not start a new synth immediately. This is useful when synths are triggered by -spawn, and a change of sound should not duplicate sends.

.fadeTime

.fadeTime = dur

set the crossfade time. See: jitlib_fading .

Setting synth controls

.set( ... args)

.map( ... args)

.setn( ... args)

NodeProxy behaves like its NodeMap and very similar to a Synth.

NOTE: Now the methods map, setn, mapn, and xmap are there just for backward compatibility reasons. Everything is done by set.

Arguments:

... args

An array of pairs: key, value, key, value, ...

The unique key (a Symbol) specifies the control name to be set.

For value anything can be specified that responds to "asControlInput", in particular:

number
set the control to that number
array of numbers
set the subsequent control channels to the corresponding value
node proxy
map subsequent control channels to the corresponding proxy output channel

.seti( ... args)

Set part of an arrayed control, analog to Synth: -seti.

Arguments:

... args

A sequence of name, index, value triplets.

name
The name of the arrayed control
index
The index into the array
value
The new value to set, can be an array to set a range of elements.

Discussion:

.unset( ... keys)

.unmap( ... keys)

Remove specified settings and unmap or unset the synths.

.xset( ... args)

set/map with a crossfade into the new setting. The crossfade time is the NodeProxy -fadeTime.

.lag( ... args)

set the lag values of these args (identical to -setRates). To remove these settings, use: lag(\key1, nil, key2, nil, ...)

.setRates( ... args)

set the default rate (\tr, \ir, numerical) for synthDef arg. A rate of nil removes setting.

.controlNames(except, addNodeMap: true)

Returns the ControlName objects of all slots, except the names of this list (default: [\out, \i_out, \gate, \fadeTime] , which are used internally). When the node proxy received a set for a given key, the defaultValue of the corresponding ControlName contains the object that was passed, which might be any object whatsoever.

.controlKeys(except, noInternalKeys: true)

Returns the keys (symbols) of all control names objects of all slots, except the names of this list. (default: none).

Arguments:

except

list of names

noInternalKeys

If noInternalKeys is true (default: true), it ignores the keys [\out, \i_out, \gate, \fadeTime] .

.getKeysValues(keys, except, withDefaults: true, noInternalKeys: true)

Get all key value pairs from both NodeMap (the settings) and default arguments.

.controlKeysValues(keys, except)

Get all key value pairs from default arguments.

.findControlName(key)

Search the source objects for a given control name symbol and return the ControlName.

.specs

Get the specs array from SynthDef metadata. Note that, for a NodeProxy with multiple sources, result will be a dictionary containing specs of ALL source SynthDefs.

Sending synths to server explicitly

Normally, processes (usually synths) are started when their respective source is added to the proxy. The processes can also be restarted, however, or the proxy can be used while asleep and the processes can then be started explicitly.

.send(extraArgs, index, freeLast: true)

Send a new synth without releasing the old one. If the source is a stream or a pattern, it starts a new one.

Arguments:

extraArgs

Arguments used to set the synth. The argument list is applied to the synth only. Arguments specified here override settings in the node map, but leave them untouched.

index

What slot to send a new synth with. If nil, uses all. (default: nil)

freeLast

if to free the last synth at that index or not (default: true)

.sendAll(extraArgs, freeLast: true)

Send all synths, or restart all objects.

Arguments:

extraArgs

Arguments used to set the synth. the argument list is applied to the synth only.

freeLast

if to free the last synth at that index or not (default: true)

.sendEach(extraArgs, freeLast: true)

Like send, just iterating separately over the objects.

.wakeUp

Until the proxy is not used by any output ( either .play or .ar/.kr ) it is not running on the server. you can wake it up to force it playing. Normally this is not needed.

Storing as code

.asCode(includeSettings: true, includeMonitor: true, envir)

From extension in /usr/local/share/SuperCollider/SCClassLibrary/JITLib/ProxySpace/extStoreOn.sc

stores the proxy as executable code. see also jitlib_asCompileString for more examples.

Inherited instance methods

Undocumented instance methods

.addChild(proxy)

.addNodeMapControlNames(objCtlNames, except: [ ])

.asGroup

.asNodeID

.asTarget

.at(index)

.children

.cleanNodeMap

.deepWakeUp

.defaultGroupID

.document(includeSettings: true, includeMonitor: true)

From extension in /usr/local/share/SuperCollider/SCClassLibrary/JITLib/ProxySpace/extStoreOn.sc

.edit(nSliders, parent, bounds)

.filter(i, func)

.findFirstSpecFor(controlName)

.findInOpenDocuments(index: 0)

From extension in /usr/local/share/SuperCollider/SCClassLibrary/JITLib/ProxySpace/extStoreOn.sc

.freeBus

.getBundle

.getFamily(set, alreadyAsked)

.getStructure(alreadyAsked)

.internalKeys

.isPlaying

.key(envir)

From extension in /usr/local/share/SuperCollider/SCClassLibrary/JITLib/ProxySpace/extStoreOn.sc

.loadToBundle(bundle)

.mapEnvir( ... keys)

.moveBeforeMsg( ... proxies)

.nameDef(name, index: 0)

.nodeID

.nodeMap

.nodeMap = map

.objects

.playEditString(usePlayN, dropDefaults: false, nameStr)

From extension in /usr/local/share/SuperCollider/SCClassLibrary/JITLib/ProxySpace/extStoreOn.sc

.playNDialog(bounds, usePlayN)

From extension in /usr/local/share/SuperCollider/SCClassLibrary/JITLib/ProxySpace/extStoreOn.sc

.playNString(dropDefaults: false)

From extension in /usr/local/share/SuperCollider/SCClassLibrary/JITLib/ProxySpace/extStoreOn.sc

.playString(dropDefaults: false)

From extension in /usr/local/share/SuperCollider/SCClassLibrary/JITLib/ProxySpace/extStoreOn.sc

.prepareOtherObjects(bundle, index, busChanged)

.prepareToBundle(argGroup, bundle, addAction: 'addToTail')

.putAll(list, index: 0, channelOffset: 0)

.putNewObject(bundle, index, container, extraArgs, now)

.putSeries(first, second, last, value)

.read(proxies)

.readFromBus(busses)

.reallocBusIfNeeded

.rebuildDeepToBundle(bundle, busWasChangedExternally: true, checkedAlready, timeArgs)

.rebuildToBundle(bundle, timeArgs)

.removeAll(fadeTime)

.removeAllToBundle(bundle, fadeTime)

.removeChild(proxy)

.removeFirst(fadeTime)

.removeToBundle(bundle, index, fadeTime)

.resetNodeMap

.sendAllToBundle(bundle, extraArgs)

.sendEachToBundle(bundle, extraArgs)

.sendObjectToBundle(bundle, object, extraArgs, index)

.servStr

From extension in /usr/local/share/SuperCollider/SCClassLibrary/JITLib/ProxySpace/extStoreOn.sc

.serverQuit

.setBus(argBus)

.setGroup(args, useLatency: false)

.setNodeMap(map, xfade: true)

.shouldAddObject(obj)

.spawn(extraArgs, index: 0)

.stopAllToBundle(bundle, fadeTime)

.supplementNodeMap(keys, replaceOldKeys: false)

.trace(index: 0)

.typeStr

.unsetToBundle(bundle, keys)

.wakeUpParentsToBundle(bundle, checkedAlready)

.wakeUpToBundle(bundle, checkedAlready)

.xFadePerform(selector, args)

.xmap( ... args)

.xsetn( ... args)

.xunset( ... args)

Examples

For more, see ProxySpace

Supported sources

NodeProxy
played by reading from the other NodeProxy bus.
Function
interpreted as ugen function, and plays a Synth, similar to Function.play.
SimpleNumber
write this value to the bus continuously, overwriting previous bus value.
Array of numbers
write the values to the bus continuously overwriting previous bus value.
Bus
read the signal on the bus.
SynthDef
plays a Synth using the SynthDef.
Symbol
plays a Synth from the SynthDef with this name.
Pattern
played as event pattern (using Pbind or other event patterns).
Stream
played as event stream (a stream returning events).
nil
Nil removes all objects.
Pdef, EventPatternProxy
played like a stream.
Task
played, no output is assigned.
Tdef
played like Task
Event
played like in a pattern.
Associations (NodeProxy roles):
(\filter -> func)
filter previous input (with post control)
(\filterIn -> func)
filter previous input (with pre control)
(\set -> event pattern)
set controls with the event keys of the pattern
(\setbus -> event pattern)
set bus with an event pattern. Bus value is the \value key of each event.
(\setsrc -> event pattern)
set the source with an event pattern. source is the \source key of event.
(\control -> array or number)
prepare an efficient way to set values by index
(\mix -> func)
mix audio
crucial library:
AbstractPlayer
started in a separate bus, mapped to this bus
Instr
converted to player and started

Definitions for other sources can be added - see: NodeProxy roles