HelpSource/Classes/Score.schelp

   1 class:: Score
   2 summary:: score of timed OSC commands
   3 related:: Guides/Non-Realtime-Synthesis
   4 categories:: Control, Server>NRT, External Control>OSC
   5
   6 description::
   7 Score encapsulates a list of timed OSC commands and provides some methods for using it, as well as support for the creation of binary OSC files for non-realtime synthesis. See link::Guides/Non-Realtime-Synthesis:: for more details.
   8
   9 The list should be in the following format, with times in ascending order. Bundles are okay.
  10
  11 code::
  12 [
  13 [beat1, [OSCcmd1]],
  14 [beat2, [OSCcmd2], [OSCcmd3]],
  15 ...
  16 [beat_n, [OSCcmdn]],
  17 [beatToEndNRT, [\c_set, 0, 0]] // finish
  18 ]
  19 ::
  20
  21 For NRT synthesis the final event should a dummy event, after which synthesis will cease. It is thus important that this event be timed to allow previous events to complete.
  22
  23 Score scheduling defaults to link::Classes/TempoClock::. A setting of code::TempoClock.default.tempo = 1 :: (60 beats per minute), may be used to express score events in seconds if desired.
  24
  25 ClassMethods::
  26
  27 private::initClass
  28
  29 method::new
  30 returns a new Score object with the supplied list.
  31
  32 argument::list
  33 can be an link::Classes/Array::, a link::Classes/List::, or similar object.
  34
  35 method::newFromFile
  36 as link::#*new::, but reads the list in from a text file.
  37
  38 argument::path
  39 a link::Classes/String:: indicating the path of the file. The file must contain a valid SC expression.
  40
  41 method::play
  42 as link::#*new:: but immediately plays it. (See also the instance method below.)
  43
  44 argument::list
  45 the list.
  46
  47 argument::server
  48 If no value is supplied it will play on the default link::Classes/Server::.
  49
  50 method::playFromFile
  51 as link::#*play::, but reads the list from a file.
  52
  53 method::write
  54 a convenience method to create a binary OSC file for NRT synthesis. Does not create an instance.
  55
  56 argument::list
  57 the list.
  58
  59 argument::oscFilePath
  60 a link::Classes/String:: containing the desired path of the OSC file.
  61
  62 argument::clock
  63 Use clock as a tempo base. code::TempoClock.default:: is used if clock is nil.
  64
  65 method::writeFromFile
  66 as link::#*write:: but reads the list from a file.
  67
  68 argument::path
  69 a path to a file with a list.
  70
  71 argument::oscFilePath
  72 a link::Classes/String:: containing the desired path of the OSC file.
  73
  74 argument::clock
  75 Use clock as a tempo base. code::TempoClock.default:: is used if clock is nil.
  76
  77 method::recordNRT
  78 a convenience method to synthesize strong::list:: in non-realtime. This method writes an OSC file to strong::oscFilePath:: (you have to do your own cleanup if desired) and then starts a server app to synthesize it. For details on valid headerFormats and sampleFormats see link::Classes/SoundFile::. Use code::TempoClock.default:: as a tempo base. Does not return an instance.
  79
  80 argument::list
  81 the list.
  82
  83 argument::oscFilePath
  84 the path to which the binary OSC file will be written.
  85
  86 argument::outputFilePath
  87 the path of the resultant soundfile.
  88
  89 argument::inputFilePath
  90 an optional path for an input soundfile.
  91
  92 argument::sampleRate
  93 the sample rate at which synthesis will occur.
  94
  95 argument::headerFormat
  96 the header format of the output file. The default is 'AIFF'.
  97
  98 argument::sampleFormat
  99 the sample format of the output file. The default is 'int16'.
 100
 101 argument::options
 102 an instance of link::Classes/ServerOptions::. If not supplied the options of the default link::Classes/Server:: will be used.
 103
 104 argument::completionString
 105
 106 argument::duration
 107
 108 argument::action
 109 A function to be evaluated once the NRT server has finished rendering its score.
 110
 111 InstanceMethods::
 112
 113 method::play
 114 play the list on strong::server::, use strong::clock:: as a tempo base and quantize start time to strong::quant::. If strong::server:: is nil, then on the default server. code::TempoClock.default:: if strong::clock:: is nil. now if strong::quant:: is 0.
 115
 116 method::stop
 117 stop playing.
 118
 119 method::write
 120 create a binary OSC file for NRT synthesis from the list. Use strong::clock:: as a tempo base. code::TempoClock.default:: if strong::clock:: is nil.
 121
 122 method::score
 123 get or set the list.
 124
 125 method::add
 126 adds bundle to the list.
 127
 128 method::sort
 129 sort the score time order. This is recommended to do strong::before recordNRT or write:: when you are not sure about the packet order.
 130
 131 method::recordNRT
 132 synthesize the score in non-realtime. For details of the arguments see link::#*recordNRT:: above.
 133
 134 method::saveToFile
 135 save the score list as a text file to strong::path::.
 136
 137 Examples::
 138
 139 subsection::NRT Examples
 140
 141 code::
 142 // A sample synthDef
 143 (
 144 SynthDef("helpscore",{ arg freq = 440;
 145         Out.ar(0,
 146                 SinOsc.ar(freq, 0, 0.2) * Line.kr(1, 0, 0.5, doneAction: 2)
 147         )
 148 }).add;
 149 )
 150
 151 // write a sample file for testing
 152 (
 153 var f, g;
 154 TempoClock.default.tempo = 1;
 155 g = [
 156         [0.1, [\s_new, \helpscore, 1000, 0, 0, \freq, 440]],
 157         [0.2, [\s_new, \helpscore, 1001, 0, 0, \freq, 660]],
 158         [0.3, [\s_new, \helpscore, 1002, 0, 0, \freq, 220]],
 159         [1, [\c_set, 0, 0]] // finish
 160         ];
 161 f = File("score-test","w");
 162 f.write(g.asCompileString);
 163 f.close;
 164 )
 165
 166 //convert it to a binary OSC file for use with NRT
 167 Score.writeFromFile("score-test", "test.osc");
 168 ::
 169
 170 From the command line, the file can then be rendered from within the build directory:
 171
 172 code::
 173 ./scsynth -N test.osc _ test.aif 44100 AIFF int16 -o 1
 174 ::
 175
 176 Score also provides methods to do all this more directly:
 177
 178 code::
 179 (
 180 var f, o;
 181 g = [
 182         [0.1, [\s_new, \helpscore, 1000, 0, 0, \freq, 440]],
 183         [0.2, [\s_new, \helpscore, 1001, 0, 0, \freq, 660],
 184                 [\s_new, \helpscore, 1002, 0, 0, \freq, 880]],
 185         [0.3, [\s_new, \helpscore, 1003, 0, 0, \freq, 220]],
 186         [1, [\c_set, 0, 0]] // finish
 187         ];
 188 o = ServerOptions.new.numOutputBusChannels = 1; // mono output
 189 Score.recordNRT(g, "help-oscFile", "helpNRT.aiff", options: o); // synthesize
 190 )
 191 ::
 192
 193 subsection::Real-time Examples
 194
 195 code::
 196 s.boot; // boot the default server
 197
 198 // A sample synthDef
 199 (
 200 SynthDef("helpscore",{ arg freq = 440;
 201         Out.ar(0,
 202                 SinOsc.ar(freq, 0, 0.2) * Line.kr(1, 0, 0.5, doneAction: 2)
 203         )
 204 }).add;
 205 )
 206
 207 // write a sample file for testing
 208 (
 209 var f, g;
 210 TempoClock.default.tempo = 1;
 211 g = [
 212         [0.1, [\s_new, \helpscore, 1000, 0, 0, \freq, 440]],
 213         [0.2, [\s_new, \helpscore, 1001, 0, 0, \freq, 660],
 214                 [\s_new, \helpscore, 1002, 0, 0, \freq, 880]],
 215         [0.3, [\s_new, \helpscore, 1003, 0, 0, \freq, 220]],
 216         [1, [\c_set, 0, 0]] // finish
 217         ];
 218 f = File("score-test","w");
 219 f.write(g.asCompileString);
 220 f.close;
 221 )
 222
 223 z = Score.newFromFile("score-test");
 224
 225 // play it on the default server
 226 z.play;
 227
 228 // change the list
 229 (
 230 x = [
 231 [0.0, [ \s_new, \helpscore, 1000, 0, 0, \freq, 1413 ]],
 232 [0.1, [ \s_new, \helpscore, 1001, 0, 0, \freq, 712 ]],
 233 [0.2, [ \s_new, \helpscore, 1002, 0, 0, \freq, 417 ]],
 234 [0.3, [ \s_new, \helpscore, 1003, 0, 0, \freq, 1238 ]],
 235 [0.4, [ \s_new, \helpscore, 1004, 0, 0, \freq, 996 ]],
 236 [0.5, [ \s_new, \helpscore, 1005, 0, 0, \freq, 1320 ]],
 237 [0.6, [ \s_new, \helpscore, 1006, 0, 0, \freq, 864 ]],
 238 [0.7, [ \s_new, \helpscore, 1007, 0, 0, \freq, 1033 ]],
 239 [0.8, [ \s_new, \helpscore, 1008, 0, 0, \freq, 1693 ]],
 240 [0.9, [ \s_new, \helpscore, 1009, 0, 0, \freq, 410 ]],
 241 [1.0, [ \s_new, \helpscore, 1010, 0, 0, \freq, 1349 ]],
 242 [1.1, [ \s_new, \helpscore, 1011, 0, 0, \freq, 1449 ]],
 243 [1.2, [ \s_new, \helpscore, 1012, 0, 0, \freq, 1603 ]],
 244 [1.3, [ \s_new, \helpscore, 1013, 0, 0, \freq, 333 ]],
 245 [1.4, [ \s_new, \helpscore, 1014, 0, 0, \freq, 678 ]],
 246 [1.5, [ \s_new, \helpscore, 1015, 0, 0, \freq, 503 ]],
 247 [1.6, [ \s_new, \helpscore, 1016, 0, 0, \freq, 820 ]],
 248 [1.7, [ \s_new, \helpscore, 1017, 0, 0, \freq, 1599 ]],
 249 [1.8, [ \s_new, \helpscore, 1018, 0, 0, \freq, 968 ]],
 250 [1.9, [ \s_new, \helpscore, 1019, 0, 0, \freq, 1347 ]],
 251 [2.0, [\c_set, 0, 0]] // finish
 252 ];
 253
 254 z.score_(x);
 255 )
 256
 257 // play it
 258 z.play;
 259
 260 // play and stop after one second
 261 (
 262 z.play;
 263 SystemClock.sched(1.0, {z.stop;});
 264 )
 265 ::
 266
 267 subsection::creating Score from a pattern
 268
 269 code::
 270 SynthDescLib.read;
 271
 272 // new pattern
 273 (
 274 p = Pbind(
 275         \dur, Prand([0.3, 0.5], inf),
 276         \freq, Prand([200, 300, 500],inf)
 277 );
 278 )
 279
 280 // make a score from the pattern, 4 beats long
 281 z = p.asScore(4.0);
 282
 283 z.score.postcs;
 284 z.play;
 285
 286 // rendering a pattern to sound file directly:
 287
 288 // render the pattern to aiff (4 beats)
 289
 290 p.render("asScore-Help.aif", 4.0);
 291 ::