class:: Monitor
summary:: link between busses
categories:: Libraries>JITLib>NodeProxy, Live Coding
related:: Reference/playN, Classes/NodeProxy, Classes/Bus

description::
A general purpose class for monitoring or crosslinking between busses. It supports multichannel expansion and crossfading between settings. It provides optimizations for playing contiguous channels to other contiguous busses (link::#play::) and for more complex routings, such as splitting, spreading etc to multiple channels (link::#playN::). Monitor uses the existing set of  link::Classes/SystemSynthDefs:: to do this.

code::
{ Out.ar(87, SinOsc.ar(MouseX.kr(240, 1000, 1) * [1, 2, 3], 0, 0.2)) }.play; // play three sine tone on channels 87, 88, and 89
x = Monitor.new; // create a new monitor
x.play(fromIndex: 87, fromNumChannels: 3, toIndex:0, toNumChannels:2); // play them back to the stereo hardware channels
::

ClassMethods::

private::warnPlayN


InstanceMethods::

method::play
Plays from a bus index with a number of channels to another index with a number of channels, within a target group, or a server.

argument::fromIndex
bus index from which to read

argument::fromNumChannels
number of channels to read from.

argument::toIndex
bus index to which to write.

argument::toNumChannels
number of channels to write. If this number is larger or smaller than fromNumChannels, wrap around. If nothing is given, uses fromNumChannels.

argument::target
where to send the synths to (default: server default group)

argument::multi
keep old links and add new one: this allows you to add layer after layer, otherwise free ther previous mapping (false by default).

argument::volume
volume at which to monitor

argument::fadeTime
specifies the fade in and fade out time

argument::addAction
where, relative to the target to place the monitor group.

code::
s.boot;
s.scope(16);

{ Out.ar(87, SinOsc.ar(MouseX.kr(40, 10000, 1) * [1, 2, 3], 0, 0.2)) }.play;
x = Monitor.new;
x.play(87, 3, 1, 2);
x.out = 0;
x.stop(3.0);
x.play(87, 1, 0, 1); // in > out : now mixes down (wrapping)
x.play(89, 1, 0, 2); // in < out : now distributes to 2 channels
x.stop;

// multiple play
x.play(87, 1, 0, 2, multi:true);
x.play(88, 1, 0, 2, multi:true);
x.play(89, 1, 0, 2, multi:true);
x.stop;
::



method::playN
Plays from an array of bus indices to another array of bus indices with an array of amplitudes, within a target group, or a server.

note::
The arguments strong::out::, strong::amp:: and strong::in:: can be nested arrays. see also link::Reference/playN::

The three arguments out, amp, and in will wrap if they do not have the same size, like this:
code::  [[0, 1], [0.1], [3, 4, 5]].flop ::
::

argument::out
array of destination channels.

argument::amp
array of amplitudes for each channel

argument::in
array of source channels

argument::vol
global scaling value for amplitudes

argument::fadeTime
specifies the fade in and fade out time

argument::target
where to play (default: server default group)

argument::addAction
where, relative to the target to place the monitor group.

argument::multi
keep old links and add new one: this allows you to add layer after layer, otherwise free ther previous mapping (false by default).

code::
// examples: args are // outs, amps, ins, vol, fadeTime

{ Out.ar(87, SinOsc.ar(MouseX.kr(40, 10000, 1) * [1, 2, 3], 0, 0.2)) }.play;
x = Monitor.new;

(
x.playN(
	[0, 1, 4], 			// to these outs
	[0.1, 0.4, 0.3], 	// with these volumes
	[87, 88, 89]		// from these ins
);
)
(
x.playN(
	[0, [1, 3, 2], 4], 		// outs can be nested: 87 -> 0, 88 -> [1, 3, 2], 89 -> 4
	[0.1, [0.4, 0.2, 0.1], 0.3],	// with nested volumes 0.1, [0.4, 0.2, 0.1], and 0.3
	[87, 88, 89]); 			// reading from these ins
)
// can also set global volume and fadetime
x.playN(vol: 0.0, fadeTime:4);
::


method::stop
Stops within the fadeTime.
note::this keeps all the settings, so when using code::play:: next time, it will play in the same configuration, overriding only values provided.::
code::
{ Out.ar(87, SinOsc.ar(MouseX.kr(340, 1000, 1) * [1, 2, 3], 0, 0.2)) }.play;
x = Monitor.new.play(87, 3, 0, fadeTime: 3);
x.stop;
x.play;
::

argument::argFadeTime
The time for fading out all routing synths.

method::clear
Stops within the fadeTime.
note::unlike code::stop::, this removes all the settings.::


method::vol
Set the volume.
code::
{ Out.ar(87, SinOsc.ar(MouseX.kr(340, 1000, 1) * [1, 2, 3], 0, 0.2)) }.play;
x = Monitor.new.play(87, 3, 0, fadeTime: 3);
x.vol = 0.3;
x.stop;
::


method::out
Set or get the first output index.

method::outs
Set or get the array of output bus indices.

method::ins
Set or get the array of input bus indices.

method::amps
Set the array of amplitudes.

method::fadeTimes
Set or get the array of fadeTimes.

method::fadeTime
Set one single fadeTime for the next transition (may be a stop or a new play).

method::isPlaying
Returns true if the group is still playing.

method::group
Return the group in which all mapping synths are running.

method::numChannels
Return the number of input channels.

method::copy
Return a copy of the receiver, with the same channel setting, but not running. You can run it with the settings by sending it the link::#play:: message, and pass in any modifications you want to make.


method::playToBundle
Adds all playing osc messages to a bundle, passed as an argument. The bundle object should implement the method strong::.add::

private::hasSeriesOuts, newGroupToBundle, playNBusToBundle, playNToBundle, stopToBundle, updateDefault, usedPlayN