1title:: play
2summary:: Start a process
3categories:: Common methods
4
5method:: play
6The code::play:: message is of common use in sc. Different objects respond to it in various
7ways, but the simple meaning is: strong::start a process::.
8It is usually implemented by objects in contributed libraries as well.
9
10play usually returns the playing object which might not be the same as the one
11the message was sent to.
12
13opposite: code::stop::
14
15section:: Clocks, Routines, Streams and Patterns
16For a full list of which classes that implements code::play::, see link::Overviews/Methods#play::
17
18subsection:: clock.play (stream)
19returns: the clock
20code::
21(
22r = Routine.new({ "...playing".postln; 1.wait; "ok, that was it".postln });
23SystemClock.play(r);
24)
25::
26See link::Classes/Clock#*play::
27
28subsection:: routine.play (clock)
29returns: the routine
30code::
31Routine.new({ "...playing".postln; 1.wait; "ok, that was it".postln }).play;
32::
33See link::Classes/Routine#-play::
34
35subsection:: stream.play (clock)
36returns: the stream
37
38the stream will loop until it returns nil
39code::
40FuncStream({ "ok, that was it".postln; 1 }).play;
41::
42See link::Classes/FuncStream#-play::
43
44subsection:: pausestream.play (clock) / task.play (clock)
45returns: the stream
46code::
47a = PauseStream.new(FuncStream.new({ "ok, that was it".postln; 1 }));
48a.play;
49a.stop;
50a.play;
51a.stop;
52
53a = Task.new({ loop({ "ok, that was it".postln; 1.wait; }) });
54a.play;
55a.stop;
56::
57See link::Classes/Stream#-play:: and link::Classes/Task#-play::
58
59subsection:: pattern.play (clock, protoEvent)
60returns: an link::Classes/EventStreamPlayer::
61code::
62(
63Pseq([
64	Pbind(\freq, Pn(500, 1)),
65	Pbind(\dur, Pn(0.1, 1))
66], 2).play;
67)
68::
69See link::Classes/Pattern#-play::
70
71section:: Playing single Synths from SynthDefs on the server
72
73The following play messages both cause a SynthDef to be written, send it to the server
74and start a synth with it there.
75
76note::
77Some UGens are added in this process.
78list::
79## an link::Classes/Out:: UGen for playing the audio to the first audio busses. If the function returns an Out UGen, this is omitted. ##an envelope with a code::gate:: control for releasing and crossfading. If the function provides its own releasable envelope, this is omitted.
80::
81Also note that they should not be used in quickly running automated processes,
82as there are more efficient alternatives ( see link::Guides/SynthDefsVsSynths:: )
83::
84
85subsection:: function.play (target, outbus, fadeTime, addAction, args)
86
87returns: a link::Classes/Synth::
88table::
89## outbus || on what bus to play (default: 0)
90## fadeTime || in what time to fade out when released (default: 0.02)
91## addAction || where to add the node (\addToHead by default)
92## args || controls to set when starting the synth
93::
94
95
96See link::Classes/Function#-play::
97
98code::
99a = { PinkNoise.ar([0.1, 0.1]) }.play;
100a.release;
101
102// setting argument
103a = { |freq = 500| HPF.ar(PinkNoise.ar([1, 1] * 0.4), freq) }.play;
104a.set(\freq, 1000)
105a.release;
106
107// passing argument with play:
108a = { |freq = 500| HPF.ar(PinkNoise.ar([1, 1] * 0.4), freq) }.play(args: [\freq, 10000]);
109
110// note that you can use Out ugens but you do not need to
111{ Out.ar(1, PinkNoise.ar(0.1)) }.play;
112{ XOut.ar(0, MouseX.kr(0,1), PinkNoise.ar(0.1*[1,1])) }.play; // mouse x controls level
113::
114
115subsection:: synthDef.play (target, args, addAction)
116returns: a link::Classes/Synth::
117
118Note that you need an out ugen to hear the result.
119Examples of how to write to the busses in the helpfiles: link::Classes/Out:: / link::Classes/ReplaceOut:: / link::Classes/XOut:: / link::Classes/OffsetOut::
120
121Nevertheless, synths can also run without any writing activity: (see e.g. link::Classes/SendTrig::)
122
123Some operations provide an out ugen internally: see for example code::function.play::, which plays out
124to a bus number provided in the argument passed to code::.play::
125
126code::
127(
128x = SynthDef(\test, { arg out, amp=0.1;
129	var sound;
130	sound = PinkNoise.ar(amp * [1,1]);
131	Out.ar(out, sound);
132}).play;
133)
134
135//set the synth
136x.set(\amp, 0.2);
137//free the synth
138x.free;
139::
140See link::Classes/SynthDef#-play::
141
142note:: code::Synth.play(function):: is synonymous, for backwards compatibility with sc2 ::
143
144