zzkt/rsc3
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
rsc3/doc-schelp/Help-3.12.2/Classes/Event.html

456 lines
42 KiB
HTML
Raw Permalink Normal View History

docs (scm, schelp, scrbl & html)
2022-08-24 13:53:18 +00:00
<html><head><title>Event</title>
<link rel='stylesheet' href='./../scdoc.css' type='text/css' />
<link rel='stylesheet' href='./../frontend.css' type='text/css' />
<link rel='stylesheet' href='./../custom.css' type='text/css' />
<meta http-equiv='Content-Type' content='text/html; charset=UTF-8' />
<script src='./../scdoc.js' type='text/javascript'></script>
<script src='./../docmap.js' type='text/javascript'></script>
<script src='./../prettify.js' type='text/javascript'></script>
<script src='./../lang-sc.js' type='text/javascript'></script>
<script type='text/javascript'>var helpRoot='./..';</script>
</head>
<ul id='menubar'></ul>
<body onload='fixTOC();prettyPrint()'>
<div class='contents'>
<div class='header'>
<div id='label'>SuperCollider CLASSES</div>
<div id='categories'><a href='./../Browse.html#Collections>Unordered'>Collections>Unordered</a>, <a href='./../Browse.html#Streams-Patterns-Events>Events'>Streams-Patterns-Events>Events</a></div>
<h1>Event</h1>
<div id='summary'>an environment that represents an action</div>
</div>
<div class='subheader'>
<div id='filename'>Source: <a href='file:///Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Collections/Event.sc'>/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Collections/Event.sc</a></div><div id='superclasses'>Inherits from: <a href="../Classes/Environment.html">Environment</a> : <a href="../Classes/IdentityDictionary.html">IdentityDictionary</a> : <a href="../Classes/Dictionary.html">Dictionary</a> : <a href="../Classes/Set.html">Set</a> : <a href="../Classes/Collection.html">Collection</a> : <a href="../Classes/Object.html">Object</a></div>
<div id='related'>See also: <a href="./../Classes/Pattern.html">Pattern</a></div>
</div>
<div id='toc'>
<ul class='toc'><li class='toc1'><a href='#description'>Description</a></li>
<ul class='toc'></ul><li class='toc1'><a href='#classmethods'>Class methods</a></li>
<ul class='toc'><li class='toc2'><a href='#Class%20variables'>Class variables</a></li>
<ul class='toc'><li class='toc3'><a href='#*parentEvents'>parentEvents</a> </li>
<li class='toc3'><a href='#*partialEvents'>partialEvents</a> </li>
</ul><li class='toc2'><a href='#Creation%20methods'>Creation methods</a></li>
<ul class='toc'><li class='toc3'><a href='#*new'>new</a> </li>
<li class='toc3'><a href='#*default'>default</a> </li>
<li class='toc3'><a href='#*silent'>silent</a> </li>
<li class='toc3'><a href='#*addEventType'>addEventType</a> </li>
<li class='toc3'><a href='#*makeDefaultSynthDef'>makeDefaultSynthDef</a> </li>
</ul><li class='toc2'><a href='#Inherited%20class%20methods'>Inherited class methods</a></li>
<li class='toc2'><a href='#Undocumented%20class%20methods'>Undocumented class methods</a></li>
<ul class='toc'><li class='toc3'><a href='#*checkIDs'>checkIDs</a> </li>
<li class='toc3'><a href='#*makeParentEvents'>makeParentEvents</a> </li>
</ul></ul><li class='toc1'><a href='#instancemethods'>Instance methods</a></li>
<ul class='toc'><li class='toc3'><a href='#-play'>play</a> </li>
<li class='toc3'><a href='#-delta'>delta</a> </li>
<li class='toc3'><a href='#-next'>next</a> </li>
<li class='toc3'><a href='#-embedInStream'>embedInStream</a> </li>
<li class='toc3'><a href='#-playAndDelta'>playAndDelta</a> </li>
<li class='toc3'><a href='#-isRest'>isRest</a> </li>
<li class='toc3'><a href='#-asUGenInput'>asUGenInput</a> </li>
<li class='toc3'><a href='#-asControlInput'>asControlInput</a> </li>
<li class='toc2'><a href='#Methods%20that%20allow%20Events%20to%20provide%20user%20control%20for%20Synths%20on%20Groups'>Methods that allow Events to provide user control for Synths on Groups</a></li>
<ul class='toc'><li class='toc3'><a href='#-synth'>synth</a> </li>
<li class='toc3'><a href='#-group'>group</a> </li>
<li class='toc3'><a href='#-stop'>stop</a> </li>
<li class='toc3'><a href='#-pause'>pause</a> </li>
<li class='toc3'><a href='#-resume'>resume</a> </li>
<li class='toc3'><a href='#-release'>release</a> </li>
<li class='toc3'><a href='#-set'>set</a> </li>
</ul><li class='toc2'><a href='#Inherited%20instance%20methods'>Inherited instance methods</a></li>
<li class='toc2'><a href='#Undocumented%20instance%20methods'>Undocumented instance methods</a></li>
<ul class='toc'><li class='toc3'><a href='#-asEvent'>asEvent</a> </li>
<li class='toc3'><a href='#-asEventStreamPlayer'>asEventStreamPlayer</a> </li>
<li class='toc3'><a href='#-asGroup'>asGroup</a> </li>
<li class='toc3'><a href='#-asOSC'>asOSC</a> </li>
<li class='toc3'><a href='#-buildForProxy'>buildForProxy</a> </li>
<li class='toc3'><a href='#-free'>free</a> </li>
<li class='toc3'><a href='#-isPlaying'>isPlaying</a> </li>
<li class='toc3'><a href='#-isRunning'>isRunning</a> </li>
<li class='toc3'><a href='#-nodeID'>nodeID</a> </li>
<li class='toc3'><a href='#-proxyControlClass'>proxyControlClass</a> </li>
<li class='toc3'><a href='#-sendOSC'>sendOSC</a> </li>
<li class='toc3'><a href='#-split'>split</a> </li>
<li class='toc3'><a href='#-synchWithQuant'>synchWithQuant</a> </li>
</ul></ul><li class='toc1'><a href='#Basic%20Usage'>Basic Usage</a></li>
<ul class='toc'><li class='toc2'><a href='#Event%20as%20a%20name%20space%20for%20keeping%20objects'>Event as a name space for keeping objects</a></li>
<ul class='toc'></ul><li class='toc2'><a href='#Event%20for%20specifying%20different%20things%20to%20happen'>Event for specifying different things to happen</a></li>
<ul class='toc'></ul><li class='toc2'><a href='#Events%20and%20SynthDefs'>Events and SynthDefs</a></li>
<ul class='toc'></ul><li class='toc2'><a href='#Multi-channel%20Expansion'>Multi-channel Expansion</a></li>
<ul class='toc'></ul><li class='toc2'><a href='#Arrayed%20Arguments'>Arrayed Arguments</a></li>
<ul class='toc'></ul><li class='toc2'><a href='#Events%20and%20Patterns'>Events and Patterns</a></li>
<ul class='toc'></ul><li class='toc2'><a href='#Event's%20play%20method'>Event's play method</a></li>
<ul class='toc'></ul><li class='toc2'><a href='#Timing%20control%20with%20Event's%20delta%20method'>Timing control with Event's delta method</a></li>
<ul class='toc'></ul><li class='toc2'><a href='#The%20structure%20of%20defaultParentEvent'>The structure of defaultParentEvent</a></li>
<ul class='toc'><li class='toc3'><a href='#.defaultParentEvent'>defaultParentEvent</a> </li>
</ul><li class='toc2'><a href='#Useful%20keys%20for%20notes'>Useful keys for notes</a></li>
<ul class='toc'></ul><li class='toc2'><a href='#Event%20types'>Event types</a></li>
<ul class='toc'></ul></ul></ul></div><h2><a class='anchor' name='description'>Description</a></h2>
<p>An Event is an Environment that specifies an action to be taken in response to a <a href="#-play">-play</a> message. The key/value pairs within the Event specify the parameters of that action. Most methods, Event inherits from its superclasses, especially from <a href="./../Classes/Dictionary.html">Dictionary</a>.<h2><a class='anchor' name='classmethods'>Class Methods</a></h2>
<h3><a class='anchor' name='Class%20variables'>Class variables</a></h3>
<h3 class='cmethodname'><span class='methprefix'>*</span><a name='*parentEvents' href='./../Overviews/Methods.html#parentEvents'>parentEvents</a> </h3>
<div class='method'>
<p>An IdentityDictionary of useful parent events.</div><h3 class='cmethodname'><span class='methprefix'>*</span><a name='*partialEvents' href='./../Overviews/Methods.html#partialEvents'>partialEvents</a> </h3>
<div class='method'>
<p>An IdentityDictionary of Events that define the default values and functions for different aspects of note generation (timing, volume, pitch, server to use, etc).</div><h3><a class='anchor' name='Creation%20methods'>Creation methods</a></h3>
<h3 class='cmethodname'><span class='methprefix'>*</span><a name='*new' href='./../Overviews/Methods.html#new'>new</a> (<span class='argstr'>n: 8</span>, <span class='argstr'>proto</span>, <span class='argstr'>parent</span>, <span class='argstr'>know: true</span>)</h3>
<div class='method'>
<p>create an event with initial size <strong>n</strong>.<h4>Arguments:</h4>
<table class='arguments'>
<tr><td class='argumentname'>n<td class='argumentdesc'>
<p>Initial size.<tr><td class='argumentname'>proto<td class='argumentdesc'>
<p>May be provided as another event which is used to override keys in the event.<tr><td class='argumentname'>parent<td class='argumentdesc'>
<p>May be provided as another event which is used to provide default keys for the event without modifying it.<tr><td class='argumentname'>know<td class='argumentdesc'>
<p>If <strong>know</strong> is set to <a href="./../Classes/True.html">True</a>, the event will respond to appropriate message calls. See <a href="./../Classes/Environment.html">Environment</a> for more details.</table></div><h3 class='cmethodname'><span class='methprefix'>*</span><a name='*default' href='./../Overviews/Methods.html#default'>default</a> </h3>
<div class='method'>
<p>Returns an empty event with <a href="#.defaultParentEvent">.defaultParentEvent</a> as parent.</div><h3 class='cmethodname'><span class='methprefix'>*</span><a name='*silent' href='./../Overviews/Methods.html#silent'>silent</a> (<span class='argstr'>dur: 1</span>, <span class='argstr'>inEvent</span>)</h3>
<div class='method'>
<p>Returns an event that describes a pause of <strong>dur</strong> duration.</div><h3 class='cmethodname'><span class='methprefix'>*</span><a name='*addEventType' href='./../Overviews/Methods.html#addEventType'>addEventType</a> (<span class='argstr'>type</span>, <span class='argstr'>func</span>)</h3>
<div class='method'>
<p>Event types define alternate play functions that are selected by the value of <strong>~type</strong>.<h4>Arguments:</h4>
<table class='arguments'>
<tr><td class='argumentname'>type<td class='argumentdesc'>
<p>A name (usually a symbol) for the event type, which can be used to select it<tr><td class='argumentname'>func<td class='argumentdesc'>
<p>A function which optionally takes the server as a first argument<pre class='code prettyprint lang-sc'>Event.addEventType(\happyEvent, { ("I am so happy to be silent sometimes, says" + ~who).postln; });
Pbind(\type, \happyEvent, \who, Prand(["Alice", "Bob", "Eve"], inf), \dur, Pwhite(0.1, 1.0, inf)).play;
// To a certain degree, it is possible to reuse some of another event type's functionality:
(
Event.addEventType(\happyEvent, { |server|
~octave = [5, 6, 7]; // always play three octaves
~detune = 10.0.rand2; // always play a bit out of tune
~type = \note; // now set type to a different one
currentEnvironment.play;
});
Pbind(\type, \happyEvent, \degree, Pseq([0, 1, 2, 3, 4, 4, 5, 5, 5, 5, 4, 2, 3, 2, 3, 1], inf), \dur, Pwhite(0.1, 1.0, inf)).play;
);</pre>
</table></div><h3 class='cmethodname'><span class='methprefix'>*</span><a name='*makeDefaultSynthDef' href='./../Overviews/Methods.html#makeDefaultSynthDef'>makeDefaultSynthDef</a> </h3>
<div class='method'>
<p>This method is called in order to build the default SynthDef, which is stored under the key <strong>\default</strong><pre class='code prettyprint lang-sc'>SynthDef(\default, { Out.ar(0, Line.kr(0.3, 0, 0.5) * SinOsc.ar(Rand(300, 500.0)) ) }).add; // overwrite default
(freq: 600).play;
Event.makeDefaultSynthDef; // reset default
(freq: 600).play;</pre>
</div><h3><a class='anchor' name='Inherited%20class%20methods'>Inherited class methods</a></h3>
<div id='inheritedclassmets'></div><h3><a class='anchor' name='Undocumented%20class%20methods'>Undocumented class methods</a></h3>
<h3 class='cmethodname'><span class='methprefix'>*</span><a name='*checkIDs' href='./../Overviews/Methods.html#checkIDs'>checkIDs</a> (<span class='argstr'>id</span>, <span class='argstr'>server</span>)</h3>
<div class='extmethod'>From extension in <a href='file:///Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc'>/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc</a></div>
<h3 class='cmethodname'><span class='methprefix'>*</span><a name='*makeParentEvents' href='./../Overviews/Methods.html#makeParentEvents'>makeParentEvents</a> </h3>
<h2><a class='anchor' name='instancemethods'>Instance Methods</a></h2>
<h3 class='imethodname'><span class='methprefix'>-</span><a name='-play' href='./../Overviews/Methods.html#play'>play</a> </h3>
<div class='method'>
<p>Play the event. This evaluates the function at <strong>\play</strong>.<pre class='code prettyprint lang-sc'>(freq: 800).play;
(play: { "I rather do something else: ".post; ~x.postln; }, x: 800.rand).play;</pre>
</div><h3 class='imethodname'><span class='methprefix'>-</span><a name='-delta' href='./../Overviews/Methods.html#delta'>delta</a> </h3>
<div class='method'>
<p>Returns the inter onset time - the time delay until the next event in a sequence. This usually depends on <strong>\dur</strong> and <strong>\stretch</strong>, but may be overridden by specifying <strong>\delta</strong> directly.<pre class='code prettyprint lang-sc'>Pn((dur: 2, freq:8000)).play;</pre>
</div><h3 class='imethodname'><span class='methprefix'>-</span><a name='-next' href='./../Overviews/Methods.html#next'>next</a> (<span class='argstr'>inval</span>)</h3>
<div class='method'>
<p>Combines an event given in the argument with the current event. This is used to enable events to be composed.<pre class='code prettyprint lang-sc'>(a: 6, b: 7).next((c: 100));</pre>
</div><h3 class='imethodname'><span class='methprefix'>-</span><a name='-embedInStream' href='./../Overviews/Methods.html#embedInStream'>embedInStream</a> (<span class='argstr'>event</span>)</h3>
<div class='supmethod'>From superclass: <a href='./../Classes/Dictionary.html'>Dictionary</a></div>
<div class='method'>
<p><h4>Arguments:</h4>
<table class='arguments'>
<tr><td class='argumentname'>event<td class='argumentdesc'>
<p>The inval, usually in an event stream. See also <a href="./../Classes/Event.html">Event</a>.
<p>If the event is not nil, yields a copy, adding all the elements of the receiver event (this leaves the receiver unchanged). If it is nil, return the receiver.<pre class='code prettyprint lang-sc'>a = (note: 2);
b = (note: [3, 5]);
Pseq([a, b]).play;</pre>
<p>If a key "embedInStream" is given, use this function instead. The behaviour of the event can be configured easily this way.
<p>The arguments event (the receiver) and inevent (the inevent) are passed to the function.<div class='note'><span class='notelabel'>NOTE:</span> In infinite patterns, you <strong>must</strong> call yield or embedInStream in the function, otherwise it will loop forever.</div><pre class='code prettyprint lang-sc'>(
a = (
pattern: Pbind(\note, Pgeom(1, 1.1, { 20.rand }), \dur, 0.05),
embedInStream: { |event, inevent| event[\pattern].embedInStream(inevent) }
);
b = (note: [3, 5]);
c = (freq: 402, dur: 0.3);
Prand([a, b, c], inf).trace.play;
)
// change the events while playing
c[\freq] = [900, 1002, 1102];
c[\freq] = [200, 101, 1102];</pre>
<p>A generator for dictionaries:<pre class='code prettyprint lang-sc'>(
d = (
a: 5, b: 7, c: 1,
rout: Routine { |inval|
inf.do { |i|
var event = d.copy.put(\count, i);
inval = event.embedInStream(inval);
}
}
);
)
// draw new values
d.rout.((z:999));
d.rout.((z:1, a:0));
d.rout.(());</pre>
</table></div><h3 class='imethodname'><span class='methprefix'>-</span><a name='-playAndDelta' href='./../Overviews/Methods.html#playAndDelta'>playAndDelta</a> (<span class='argstr'>cleanup</span>, <span class='argstr'>mute</span>)</h3>
<div class='method'>
<p>Used by <a href="./../Classes/EventStreamPlayer.html">EventStreamPlayer</a> to play Events and obtain a time increment.</div><h3 class='imethodname'><span class='methprefix'>-</span><a name='-isRest' href='./../Overviews/Methods.html#isRest'>isRest</a> </h3>
<div class='method'>
<p>Returns <strong>true</strong> if the event will be played as a rest, and <strong>false</strong> otherwise. See <a href="./../Classes/Rest.html">Rest</a> for a more complete discussion of rests in event patterns.</div><h3 class='imethodname'><span class='methprefix'>-</span><a name='-asUGenInput' href='./../Overviews/Methods.html#asUGenInput'>asUGenInput</a> </h3>
<div class='method'>
<p>Calls <a href="#-asControlInput">-asControlInput</a>.</div><h3 class='imethodname'><span class='methprefix'>-</span><a name='-asControlInput' href='./../Overviews/Methods.html#asControlInput'>asControlInput</a> </h3>
<div class='method'>
<p>Enables events to represent the server resources they created in an Event.</div><h3><a class='anchor' name='Methods%20that%20allow%20Events%20to%20provide%20user%20control%20for%20Synths%20on%20Groups'>Methods that allow Events to provide user control for Synths on Groups</a></h3>
<h3 class='imethodname'><span class='methprefix'>-</span><a name='-synth' href='./../Overviews/Methods.html#synth'>synth</a> </h3>
<div class='extmethod'>From extension in <a href='file:///Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc'>/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc</a></div>
<div class='method'>
<p>Makes the event a control interface to the resultant <a href="./../Classes/Synth.html">Synth</a> when played.</div><h3 class='imethodname'><span class='methprefix'>-</span><a name='-group' href='./../Overviews/Methods.html#group'>group</a> </h3>
<div class='extmethod'>From extension in <a href='file:///Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc'>/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc</a></div>
<div class='method'>
<p>Makes the event a control interface to the resultant <a href="./../Classes/Group.html">Group</a> when played. This is experimental, does not work consistently yet.</div><h3 class='imethodname'><span class='methprefix'>-</span><a name='-stop' href='./../Overviews/Methods.html#stop'>stop</a> </h3>
<div class='extmethod'>From extension in <a href='file:///Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc'>/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc</a></div>
<div class='method'>
<p>Free the <a href="./../Classes/Synth.html">Synth</a> or <a href="./../Classes/Group.html">Group</a>.</div><h3 class='imethodname'><span class='methprefix'>-</span><a name='-pause' href='./../Overviews/Methods.html#pause'>pause</a> </h3>
<div class='extmethod'>From extension in <a href='file:///Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc'>/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc</a></div>
<div class='method'>
<p>Pause the <a href="./../Classes/Synth.html">Synth</a> or <a href="./../Classes/Group.html">Group</a>.</div><h3 class='imethodname'><span class='methprefix'>-</span><a name='-resume' href='./../Overviews/Methods.html#resume'>resume</a> </h3>
<div class='extmethod'>From extension in <a href='file:///Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc'>/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc</a></div>
<div class='method'>
<p>Resume the <a href="./../Classes/Synth.html">Synth</a> or <a href="./../Classes/Group.html">Group</a>.</div><h3 class='imethodname'><span class='methprefix'>-</span><a name='-release' href='./../Overviews/Methods.html#release'>release</a> (<span class='argstr'>releaseTime</span>)</h3>
<div class='extmethod'>From extension in <a href='file:///Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc'>/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc</a></div>
<div class='method'>
<p>Release the <a href="./../Classes/Synth.html">Synth</a> or <a href="./../Classes/Group.html">Group</a>.</div><h3 class='imethodname'><span class='methprefix'>-</span><a name='-set' href='./../Overviews/Methods.html#set'>set</a> ( <span class='argstr'>... args</span>)</h3>
<div class='extmethod'>From extension in <a href='file:///Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc'>/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc</a></div>
<div class='method'>
<p>Set a control value in the <a href="./../Classes/Synth.html">Synth</a> or <a href="./../Classes/Group.html">Group</a>. (key1, val1, ....)<pre class='code prettyprint lang-sc'>a = (note: 2).play;
a.set(\freq, 700);
a.release;</pre>
</div><h3><a class='anchor' name='Inherited%20instance%20methods'>Inherited instance methods</a></h3>
<div id='inheritedinstmets'></div><h3><a class='anchor' name='Undocumented%20instance%20methods'>Undocumented instance methods</a></h3>
<h3 class='imethodname'><span class='methprefix'>-</span><a name='-asEvent' href='./../Overviews/Methods.html#asEvent'>asEvent</a> </h3>
<div class='extmethod'>From extension in <a href='file:///Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/Rest.sc'>/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/Rest.sc</a></div>
<h3 class='imethodname'><span class='methprefix'>-</span><a name='-asEventStreamPlayer' href='./../Overviews/Methods.html#asEventStreamPlayer'>asEventStreamPlayer</a> </h3>
<div class='extmethod'>From extension in <a href='file:///Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc'>/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc</a></div>
<h3 class='imethodname'><span class='methprefix'>-</span><a name='-asGroup' href='./../Overviews/Methods.html#asGroup'>asGroup</a> </h3>
<div class='extmethod'>From extension in <a href='file:///Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc'>/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc</a></div>
<h3 class='imethodname'><span class='methprefix'>-</span><a name='-asOSC' href='./../Overviews/Methods.html#asOSC'>asOSC</a> </h3>
<div class='extmethod'>From extension in <a href='file:///Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Control/asScore/asScore.sc'>/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Control/asScore/asScore.sc</a></div>
<h3 class='imethodname'><span class='methprefix'>-</span><a name='-buildForProxy' href='./../Overviews/Methods.html#buildForProxy'>buildForProxy</a> (<span class='argstr'>proxy</span>, <span class='argstr'>channelOffset: 0</span>)</h3>
<div class='extmethod'>From extension in <a href='file:///Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/JITLib/ProxySpace/wrapForNodeProxy.sc'>/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/JITLib/ProxySpace/wrapForNodeProxy.sc</a></div>
<h3 class='imethodname'><span class='methprefix'>-</span><a name='-free' href='./../Overviews/Methods.html#free'>free</a> </h3>
<div class='extmethod'>From extension in <a href='file:///Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc'>/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc</a></div>
<h3 class='imethodname'><span class='methprefix'>-</span><a name='-isPlaying' href='./../Overviews/Methods.html#isPlaying'>isPlaying</a></h3>
<h3 class='imethodname'><span class='methprefix'>-</span><a name='-isPlaying' href='./../Overviews/Methods.html#isPlaying'>isPlaying</a> = <span class='argstr'>val</span></h3>
<div class='supmethod'>From superclass: <a href='./../Classes/Object.html'>Object</a></div>
<h3 class='imethodname'><span class='methprefix'>-</span><a name='-isRunning' href='./../Overviews/Methods.html#isRunning'>isRunning</a> = <span class='argstr'>val</span></h3>
<h3 class='imethodname'><span class='methprefix'>-</span><a name='-nodeID' href='./../Overviews/Methods.html#nodeID'>nodeID</a> </h3>
<div class='extmethod'>From extension in <a href='file:///Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc'>/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc</a></div>
<h3 class='imethodname'><span class='methprefix'>-</span><a name='-proxyControlClass' href='./../Overviews/Methods.html#proxyControlClass'>proxyControlClass</a> </h3>
<div class='extmethod'>From extension in <a href='file:///Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/JITLib/ProxySpace/wrapForNodeProxy.sc'>/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/JITLib/ProxySpace/wrapForNodeProxy.sc</a></div>
<h3 class='imethodname'><span class='methprefix'>-</span><a name='-sendOSC' href='./../Overviews/Methods.html#sendOSC'>sendOSC</a> (<span class='argstr'>msg</span>)</h3>
<div class='extmethod'>From extension in <a href='file:///Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc'>/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc</a></div>
<h3 class='imethodname'><span class='methprefix'>-</span><a name='-split' href='./../Overviews/Methods.html#split'>split</a> (<span class='argstr'>key: 'id'</span>)</h3>
<div class='extmethod'>From extension in <a href='file:///Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc'>/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Streams/NodeEvents.sc</a></div>
<h3 class='imethodname'><span class='methprefix'>-</span><a name='-synchWithQuant' href='./../Overviews/Methods.html#synchWithQuant'>synchWithQuant</a> (<span class='argstr'>quant</span>)</h3>
<h2><a class='anchor' name='Basic%20Usage'>Basic Usage</a></h2>
<p>Events can be written as a series of key value pairs enclosed in parentheses. Empty parentheses will create an empty event. They may be also used for object prototyping - see <a href="./../Classes/Environment.html">Environment</a> for more details.<h3><a class='anchor' name='Event%20as%20a%20name%20space%20for%20keeping%20objects'>Event as a name space for keeping objects</a></h3>
<p>Because of this simple syntax, Events are often used as name space for keeping objects:<pre class='code prettyprint lang-sc'>// using an event to store values
q = (n: 10, x: [1, 2, 3]);
q[\y] = q[\x] * q[\n]; // similar to ~y = ~x * ~n, but in a separate name space
q.y = q.x * q.n; // shorter way to do the same (pseudo-methods)
q.y; // [ 100, 200, 300 ]</pre>
<h3><a class='anchor' name='Event%20for%20specifying%20different%20things%20to%20happen'>Event for specifying different things to happen</a></h3>
<p>Event provides a <a href="#.defaultParentEvent">.defaultParentEvent</a> that defines a variety of different event types and provides a complete set of default key/value pairs for each type. The type is determined by the value of the key <strong>\type</strong> which defaults to <strong>\note</strong>. Note events create synths on the server.<pre class='code prettyprint lang-sc'>( ).play; // the default note
(freq: 500, pan: -1) .play; // 500 Hz, panned left
(play: { ~what.postln }, what: "hello happening").play; // something else</pre>
<p>Per default, the play message derives its behaviour from the <a href="#.defaultParentEvent">.defaultParentEvent</a>, which provides many default values, such as default instrument (\default), note (0), legato (0.8) and so on. Depending on the event type, these may differ completely and need not even represent a sound.<h3><a class='anchor' name='Events%20and%20SynthDefs'>Events and SynthDefs</a></h3>
<p>The key used to select what synthdef is to be played is <strong>\instrument</strong>. In order to use a <a href="./../Classes/SynthDef.html">SynthDef</a> with an Event, send it an <strong>add</strong> message. This creates a description of the SynthDef that the event can consult to determine its control names. The values of these names in the event are used when the event is played. (See <a href="./../Classes/SynthDesc.html">SynthDesc</a> for details.)<pre class='code prettyprint lang-sc'>(
SynthDef(\pm, { |out=0, freq=440, amp=0.1, pan=0, gate=1, ratio = 1, index = 1, ar = 0.1, dr = 0.1|
var z;
z = LPF.ar(
PMOsc.ar(freq, freq * ratio, Linen.kr(gate, ar,index, dr), 0, 0.3),
XLine.kr(Rand(4000, 5000), Rand(2500, 3200), 1)
) * Linen.kr(gate, 0.01, 0.7, dr, 2);
OffsetOut.ar(out, Pan2.ar(z, pan, amp));
}).add;
);
(instrument: \pm).play;
(instrument: \pm, ratio: 3.42, index: 12, freq: 150, ar: 8, dr: 3, sustain: 10).play;</pre>
<div class='note'><span class='notelabel'>NOTE:</span> The use of <a href="./../Classes/OffsetOut.html">OffsetOut</a> in the SynthDef prevents irregularities that can result from the interaction of the timing of a sequence of notes and the control rate of the Server.</div><h3><a class='anchor' name='Multi-channel%20Expansion'>Multi-channel Expansion</a></h3>
<p>If a key relevant to the action is assigned an <a href="./../Classes/Array.html">Array</a>, the action is repeated on each element of the array:<pre class='code prettyprint lang-sc'>(degree: (0..12)).play; // a diatonic cluster</pre>
<p>If several keys are assigned arrays, the action is repeated for each element of the largest array. Smaller arrays are rotated through repeatedly. Here are some examples:<pre class='code prettyprint lang-sc'>// every other note of the diatonic cluster: stacked thirds
(degree: (0..12), amp: [0, 0.1]).play;
// every other note of the semitone cluster: a wholetone cluster again
(note: (0..12), amp: [0, 0.1]).play;
// every third note of the semitone cluster: a diminished chord
(note: (0..12), amp: [0, 0, 0.1]).play;
// the same with different sustain times
(note: (0..12), amp: [0, 0, 0.1], sustain:[0.1, 0.3, 1.3, 2.5]).play;
// timingOffset gives a tempo-relative offset time to each synth
(instrument: \pm, ratio: [2.3, 4.5, 1.7], timingOffset: [0, 1.2, 3], sustain: [0.2, 2, 1]).play;</pre>
<p>In the \note event, all keys multichannel expand apart from: \instrument, \dur, \delta, \strum.<h3><a class='anchor' name='Arrayed%20Arguments'>Arrayed Arguments</a></h3>
<p>It is possible to assign an array to one of a <a href="./../Classes/SynthDef.html">SynthDef</a>'s control names. For example:<pre class='code prettyprint lang-sc'>(
SynthDef(\test, { | out = 0, amp = 0.01, freq = #[300,400,400], pan, gate = 1 |
var audio, env;
audio = Mix.ar(Pulse.ar(freq, 0.5)); // this is a mixture of three oscillators
env = Linen.kr(gate, susLevel: amp , doneAction: 2); // envelope deletes the synt when done
audio = audio * env;
OffsetOut.ar(0, audio );
}).add;
)</pre>
<p>Within an event, arrayed arguments of this sort must be enclosed within an additional array to distinguish them from arguments intended for multi-channel expansion.<pre class='code prettyprint lang-sc'>// one synth, use enclosing array to prevent multi-channel expansion
(instrument: \test, note: [[0, 2, 4]]).play;
// two synths
(instrument: \test, note: [[0, 2, 4], [6, 8, 10]]).play;</pre>
<h3><a class='anchor' name='Events%20and%20Patterns'>Events and Patterns</a></h3>
<p>Events are closely integrated with the Patterns library. Different patterns can be bound to different keys (or collections of keys) to specify the resultant music. See the help files <a href="./../Classes/Pattern.html">Pattern</a> and <a href="./../Classes/Pbind.html">Pbind</a> and the tutorials <a href="./../Tutorials/Streams-Patterns-Events4.html">Understanding Streams, Patterns and Events - Part 4</a> and <a href="./../Tutorials/Streams-Patterns-Events5.html">Understanding Streams, Patterns and Events - Part 5</a> for more details on Patterns.
<p>Patterns that return events may be played on a clock: dur specifies the time between two subsequent events.<pre class='code prettyprint lang-sc'>// Pseq returns one item in the list after the other
(
Pseq([
(note: 2, sustain: 1, dur: 1.5),
(note: [5, 7], sustain: 0.5, dur: 0.8),
(note: [2, 6], sustain: 1, dur: 0.8)
]).play;
)
// Pbind binds parameters to events:
(
Pbind(
\note, Pseq([2, [5, 7], [2, 6]]),
\sustain, Pseq([1, 0.5, 1]),
\dur, Pseq([1.5, 0.8, 0.8])
).play;
)
// per-event timing may be specified:
(
Pbind(
\note, Pseq([[0, 9], [5, 7], [2, 6]], inf),
\sustain, Pseq([1, 0.5, 1], inf),
\dur, Pseq([1.5, 0.8, 0.8], inf),
\timingOffset, Pseq([[0, 0.3], [0, 0.01]], inf)
).play;
)</pre>
<p>Here is an example that illustrates some more of the keys defined by the <a href="#.defaultParentEvent">.defaultParentEvent</a>. Note that it is equivalent to write <code class='code prettyprint lang-sc'>Pbind(\key, val, ...)</code> and <code class='code prettyprint lang-sc'>Pbind(*[key: val, ...])</code>.<pre class='code prettyprint lang-sc'>(
Pbind(*[
stepsPerOctave: Pstep(Pseq((2..12).mirror, inf),12), // 3 - 12 tone e.t. scales
note: Pseq((0..12).mirror, inf), // play full notes up and down
ctranspose: Pwhite(-0.2, 0.2), // detune up to +-20 cents
detune: Pwhite(-1.0, 1.0), // detune up to 1 Hz
sustain: Prand([0.2, 0.2, 0.2, 4], inf), // notes last 0.2 or 4 seconds
// 1 in 6 chance waits 0.8 seconds:
dur: Prand([0.2, 0.2, 0.2, 0.2, 0.2, 0.8], inf),
db: Pstep(Pseq([-15, -25, -20, -25], inf), 0.8)// 4 beat accent structure
]).play;
)</pre>
<h3><a class='anchor' name='Event's%20play%20method'>Event's play method</a></h3>
<p>When an Event (or any other <a href="./../Classes/Environment.html">Environment</a>) receives a <code class='code prettyprint lang-sc'>use(function)</code> message, it sets itself to be currentEnvironment, evaluates the function, and restores the original value of currentEnvironment. This allows the function to access and alter the contents of the event using the following shortcuts: <code class='code prettyprint lang-sc'>~keyName</code> which is equivalent to <code class='code prettyprint lang-sc'>currentEnvironment.at(keyName)</code> and <code class='code prettyprint lang-sc'>~keyName = value</code> which is equivalent to <code class='code prettyprint lang-sc'>currentEnvironment.put(keyName, value)</code>.
<p>We will write <code class='code prettyprint lang-sc'>~keyName</code> whenever referring to the value stored at the key keyName in the event.
<p>Here is the definition of Event's play method:<pre class='code prettyprint lang-sc'>play {
if (parent.isNil) { parent = defaultParentEvent };
this.use { ~play.value };
}</pre>
<p>Thus we can see that the <a href="#.defaultParentEvent">.defaultParentEvent</a> is used unless otherwise specified and the function stored in <code class='code prettyprint lang-sc'>~play</code> is executed in the context of the Event. It can be replaced in a given event for different behavior:<pre class='code prettyprint lang-sc'>(a: 6, b: 7, play: { (~a * ~b).postln }).play;</pre>
<h3><a class='anchor' name='Timing%20control%20with%20Event's%20delta%20method'>Timing control with Event's delta method</a></h3>
<p>Events also specify timing within a <a href="./../Classes/Pattern.html">Pattern</a>. Event's <code class='code prettyprint lang-sc'>delta</code> method returns the value of <code class='code prettyprint lang-sc'>~delta</code> or, if that is nil, <code class='code prettyprint lang-sc'>~dur * ~stretch</code>.
<p>Patterns are played by <a href="./../Classes/TempoClock.html">TempoClock</a>s, which have their own tempo controls. This tempo which can be controlled through <code class='code prettyprint lang-sc'>~tempo</code> in the event. Changes to the tempo affect everything else scheduled by the TempoClock, so <code class='code prettyprint lang-sc'>tempo</code> provides a global tempo control while <code class='code prettyprint lang-sc'>stretch</code> provides a control limited to the one pattern.<h3><a class='anchor' name='The%20structure%20of%20defaultParentEvent'>The structure of defaultParentEvent</a></h3>
<h3 class='imethodname'><span class='methprefix'>&nbsp;</span><a name='.defaultParentEvent' href='./../Overviews/Methods.html#defaultParentEvent'>defaultParentEvent</a> </h3>
<div class='method'>
<p>The default event used in most cases. This is a private class variable. See <a href="#*default">*default</a>.
<p>The default parent event provides the collection of default values and functions needed for the different uses of an Event. These defaults are defined in partialEvents that specify distinct aspects of default parent Event:<pre class='code prettyprint lang-sc'>playerEvent // defines ~play, ~type and ~eventTypes
serverEvent // server, group, addAction
durEvent // duration, tempo and articulation
ampEvent // volume, pan, MIDI velocity
pitchEvent // pitch specified in many different ways
bufferEvent // buffers on the server
midiEvent // defines the sending of midi messages</pre>
</div><h3><a class='anchor' name='Useful%20keys%20for%20notes'>Useful keys for notes</a></h3>
<p>Using Events is largely a matter of overwriting keys. Here is a list of keys useful for defining notes with their default values, grouped by the partialEvent within which they are defined.<ul>
<li><strong>serverEvent keys</strong>:
<p>The keys in serverEvent provide the values needed to identify the server to be used and where in the tree of nodes to place the group.<pre class='code prettyprint lang-sc'>server: nil, // if nil, Server.default is used
instrument: \default, // this is the name of a SynthDef
group: 1, // nodeID of group on the server
// when adding before or after a node
// this could be the nodeID of a synth instead of a group
addAction: 0, // 0, 1, 2, 3 or \addToHead, \addToTail, \addBefore, \addAfter
out: 0, // usually an output bus number, but depends on the SynthDef</pre>
<li><strong>ampEvent keys</strong>:
<p>The ampEvent determines volume. Notice that <code class='code prettyprint lang-sc'>~amp</code> is a function that determines its value from <code class='code prettyprint lang-sc'>~db</code>. The user can choose to specify the amplitude directly by overwriting <code class='code prettyprint lang-sc'>~amp</code> or to use a decibel specification by overwriting <code class='code prettyprint lang-sc'>~db</code>.<pre class='code prettyprint lang-sc'>amp: #{ ~db.dbamp }, // the amplitude
db: -20.0, // the above described in decibel
pan: 0.0, // pan position: -1 left 1 right
velocity: 64 // midi velocity
trig: 0.5 // trigger value</pre>
<li><strong>durEvent keys</strong>:
<p>The durEvent has keys that determine the timing of a note. Notice that <code class='code prettyprint lang-sc'>~sustain</code> is a function that uses <code class='code prettyprint lang-sc'>~legato</code> to determine the sustain. Like <code class='code prettyprint lang-sc'>~amp</code> this can be overwritten to set the sustain directly.<pre class='code prettyprint lang-sc'>tempo: nil, // changes tempo of a TempoClock
dur: 1.0, // time until next note (inter-onset time)
stretch: 1.0, // inverse of tempo control, specific to the Event's stream
legato: 0.8, // ratio of sustain to duration
sustain: #{ ~dur * ~legato * ~stretch },
lag: 0.0, // delay (in seconds) relative to current time position of Stream
timingOffset: 0.0, // delay (in beats) relative to current time position of Stream
strum: 0.0 // "breaks" a chord. May be negative, playing the chord backward
strumEndsTogether: false // if true, the strummed notes end together (with gated synths)
sendGate: nil // override: true == always send a gate-release message; false == never send</pre>
<li><strong>pitchEvent keys</strong>:
<p>The pitchEvent has the most complex system of functions that provide a variety of useful ways to determine pitch:<pre class='code prettyprint lang-sc'>freq (-&gt;440) // determines the pitch directly as a frequency in Hertz
midinote (-&gt; 60) // determines pitch as a fractional MIDI note (69 -&gt; 440)
note (-&gt; 0) // determines pitch as a scale degree in an ~stepsPerOctave equal tempered scale
degree: 0 // determines pitch as a scale degree within the scale ~scale</pre>
<p>The event also provides a set of transposition keys:<pre class='code prettyprint lang-sc'>mtranspose: 0 // modal transposition of degree within a scale
root: 0.0 // transposes root of the scale
gtranspose: 0.0 // gamut transposition within the ~stepsPerOctave equal tempered scale
ctranspose: 0.0 // chromatic transposition within the 12 tone equal tempered scale
harmonic: 1.0 // multiplies the frequency determined by ~midinote, typically to an overtone
detune: 0.0 // directly offsets frequency by adding this value
midiToCps // a function taking a MIDI note number and turning it into frequency
// Normally this is _.midicps, but you can override it for non-ET tunings
mtranspose: 0, // modal transposition of degree
gtranspose: 0.0 // gamut transposition of note within a ~stepsPerOctave e.t. scale
ctranspose: 0.0 // chromatic transposition of midinote within 12 tone e.t. scale
octave: 5.0 // octave offest of note
root: 0.0 // root of the scale
degree: 0 // degree in scale
scale: #[0, 2, 4, 5, 7, 9, 11] // diatonic major scale
stepsPerOctave: 12.0 //
detune: 0.0, // detune in Hertz
harmonic: 1.0 // harmonic ratio
octaveRatio: 2.0 // size of the octave (can be used with the Scale class)</pre>
<p>The event calculates with these keys to derive parameters needed for the synth:<pre class='code prettyprint lang-sc'>note: #{ // note is the note in halftone steps from the root
(~degree + ~mtranspose).degreeToKey(~scale, ~stepsPerOctave);
}
midinote: #{ // midinote is the midinote (continuous intermediate values)
((~note.value + ~gtranspose + ~root) / ~stepsPerOctave + ~octave) * 12.0;
}
freq: #{
(~midinote.value + ~ctranspose).midicps * ~harmonic;
}
detunedFreq: #{ // finally sent as "freq" to the synth as a parameter, if given
~freq.value + ~detune
}</pre>
<div class='image'><img src='Event-default-note.png'/></div>
</ul>
<h3><a class='anchor' name='Event%20types'>Event types</a></h3>
<p>An Event responds to a play message by evaluating <code class='code prettyprint lang-sc'>~play</code> in the event, which by default uses the event's type to define the action to be performed. See <a href="./../Overviews/Event_types.html">Event types</a>.<div class='doclink'>helpfile source: <a href='file:///Applications/SuperCollider.app/Contents/Resources/HelpSource/Classes/Event.schelp'>/Applications/SuperCollider.app/Contents/Resources/HelpSource/Classes/Event.schelp</a><br>link::Classes/Event::<br>sc version: 3.8.0</div></div></body></html>
Reference in a new issue Copy permalink