When you boot a SuperCollider server (scsynth, or supernova on supported systems) normally, it runs in realtime mode:
If the server starts with the -N switch, it runs in non-realtime (NRT) mode:
When to use NRT mode: If the audio processing can be arranged fully in advance, and you need "faster-than-light" processing (or the processing is too heavy to complete in real time), NRT may be appropriate.
When not to use NRT mode: If you need to interact with the server process at specific times, NRT is not appropriate. For instance, if your code makes decisions about upcoming events based on data received from SendReply, Bus: -get (/c_get) or Buffer: -get (/b_get), or node notification messages, these data will not be available in NRT mode.
It is recommended to use a Score object to run NRT processes. A Score object:
A new Score object needs a list of commands, with times.
Each command is an array, e.g. ['/n_set', 1000, 'gate', 0].
Each command is bound to a time by placing it in another array, with the time (a floating point number, in beats) first:
TempoClock.default will be used.Server abstraction objects (Synth, Group, Buffer etc.) include methods to give you the OSC message. So, a Score may frequently include idioms such as:
[time, Group.basicNew(server).newMsg][time, Synth.basicNew(\defname, server).newMsg(target, args: [...])][time, Buffer(server).allocReadMsg(path)]Synth.new(...) transmits /s_new; Buffer.alloc(server, ...) sends /b_alloc. To build a NRT score, create the object as a placeholder (no immediate communication) and then ask a placeholder for the message: Synth: *basicNew and Synth: -newMsg, or Buffer: *new and Buffer: -allocMsg or Buffer: -allocReadMsg. There is no need for a bus-allocation message simmilar to Buffer: -allocMsg. If you have only used realtime synthesis, this code style is unfamiliar, but it's worth practicing.
(The result of, e.g., newMsg is already the array representing the message. So it is sufficient for each Score item to be an array containing the time and method call. The subarray should be explicit only when writing the message by hand.)
Consult help files for the server abstraction classes for additional "...Msg" methods.
If you save the result of Synth.basicNew(...) in a variable, then you can free it later using either Node: -freeMsg or Node: -releaseMsg, e.g.:
For SynthDef, there is no addMsg or recvMsg method. Add SynthDefs into the Score as follows:
Very large SynthDefs will need to be written to disk and not rendered as OSC messages in the Score. The SuperCollider language client limits the size of a single OSC message to 65516 bytes. If a SynthDef exceeds this limit, creation of the Score object will fail with the error message ERROR: makeSynthMsgWithTags: buffer overflow. Resolve this error message as follows:
To render the Score, use the Score: -recordNRT method. Here is a rough template, followed by an explanation of the recordNRT parameters.
nil). Score will generate a temporary filename for you.ServerOptions.new.numOutputBusChannels_(2).Of these, outputFilePath, options and duration are particularly important. Make sure you specify at least these.
duration for recordNRT, Score will automatically append a dummy command at the end of the score, with the given timestamp, ensuring that the output file will be at least this long.If you are repeatedly rendering NRT scores, you can set Score.options = ServerOptions.new... and recordNRT will use this set of server options by default.
recordNRT allows you optionally to specify the path to the binary OSC score file. This is useful if you want to keep the file for archival purposes, or to delete the file in recordNRT's action function.
If you do not give a path, recordNRT will generate one for you in the system's temporary file location. These files are not automatically deleted after rendering. Some systems may automatically clean up old temporary files after some time. Otherwise, you can take it into your own hands:
If you want to use server abstraction objects (e.g. Synth, Group, Buffer), you might also want them to allocate node IDs or buffer and bus numbers for you. Synth: *basicNew and Buffer: *new use the server's allocators if you don't supply an ID (leave it nil). However, if you accidentally use the default server, any IDs you allocate for NRT will be marked as allocated in the default, realtime server. To avoid this, you can create a separate Server instance, just for producing the Score, and then remove the instance after rendering. This is a client-only object; you don't need to boot it.
It is technically incorrect to use the default server s for Score generation, but for quick and dirty uses, it may be acceptable. The examples in this document demonstrate the use of a dedicated Server object as a best practice. Following this best practice is likely to avoid problems in which NRT Score generation affect the default server instance; however, in common usage, such problems might not be severe. "At the user's own risk."
A NRT server is a separate server process from any other. Every time you run a Score, it launches a brand-new server process. Each new server starts with a blank slate. In particular, any SynthDefs you have added or Buffers you have loaded are not automatically available to the new server.
Therefore, your Score must include instructions to prepare these resources.
It is a very common mistake to load a buffer into a realtime server, and then run a non-realtime server, and find that resources are not available. For instance, this example adds a SynthDef in the normal way (added in memory only), and the SynthDef is not automatically transferred to the NRT server.
-> nextOSCPacket 0 *** ERROR: SynthDef NRTsine not found FAILURE IN SERVER /s_new SynthDef not found
.scsyndef files on disk that you might not need later. For that reason, this document demonstrates how to make SynthDefs available to NRT servers without using disk files.The good news is that a NRT server does not have to wait for "heavy" operations like receiving SynthDefs or loading buffers. Commands that are considered asynchronous in a realtime server behave as synchronous commands in NRT. So, you can simply front-load your Score with all the SynthDefs and Buffers, at time 0.0, and then start the audio processing also at time 0.0. (However, you might need a slight offset for the audio processing because sort may not know which entries at time 0.0 must come first.) The following examples demonstrate.
The preceding example, for simplicity, adds only one synth. Another approach is to create the initial Score with "setup" messages, and add further Synth messages for notes.
Applying a custom effect to a very long audio file is an especially good use of NRT: create a Score that defines an effect SynthDef and runs it for the duration of of the input file. You can use recordNRT's input file parameter to pipe the source audio to the NRT server's hardware inputs, and read it with SoundIn.
The example audio file is not very long, but processing here is almost instantaneous.
Event patterns can be converted into Scores by asScore. (Note that asScore internally creates a Server instance to use for allocators. So, it is not necessary for this example to create a Server.)
First, a simple example using the default SynthDef. Note that the default SynthDef is not stored to disk by default, so it is necessary to include it in the score. The slight time offset in asScore is necessary to be sure that the SynthDef message comes first.
To use Buffers and Buses, it is recommended to avoid conflicts with real-time server instances by creating a Server object just for the non-realtime process. It is not necessary to boot this server, only to use its allocators. After rendering, you may safely remove the server instance.
See also Pproto for another way to initialize buffers and other resources within a pattern object. Not every type of resource is supported in Pproto, but for typical cases, it may be more convenient than the above approach.
An NRT server may also be used to extract analytical data from a sound file. The main issues are:
/dev/null for the output file path. In Windows, use NUL.If, for some reason, you need to write the OSC command file yourself without using Score, the general method is:
File(path, "w").cmd.cmd = cmd.asRawOSC;file.write(cmd.size);file.write(cmd);In this example, a control bus and LFO map is used to have various affects on the source sound.