Guides | Server > NRT | External Control > OSC

Non-Realtime Synthesis (NRT)

Non-realtime synthesis with binary files of OSC commands

Realtime vs. Non-Realtime Synthesis

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.

Basic usage of Score

It is recommended to use a Score object to run NRT processes. A Score object:

Timed messages

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:

NOTE: Times are adjusted for the clock's tempo. Score: *new allows you to specify a TempoClock; if you don't, then 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:

NOTE: Normal usage of Synth or Buffer communicates immediately with the server: 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:

Rendering a Score using 'recordNRT'

To render the Score, use the Score: -recordNRT method. Here is a rough template, followed by an explanation of the recordNRT parameters.

oscFilePath
Recommended to omit (leave as nil). Score will generate a temporary filename for you.
outputFilePath
The output audio file that you want (full path).
inputFilePath
Optional. If you provide an existing audio file, its contents will stream to the NRT server's hardware input buses.
sampleRate
Output file sample rate.
headerFormat
See SoundFile: -headerFormat.
sampleFormat
See SoundFile: -sampleFormat.
options
An instance of ServerOptions. In particular, this is important to set the desired number of output channels, e.g. ServerOptions.new.numOutputBusChannels_(2).
completionString
Undocumented. No apparent purpose.
duration
The desired total length of the output file, in seconds.
action
A function to evaluate when rendering is complete.

Of these, outputFilePath, options and duration are particularly important. Make sure you specify at least these.

NOTE: NRT processing continues until the last timestamp in the score file. If you specify a 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.

Score files

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:

Server instance

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."

Server resources

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
NOTE: Another common technique to transmit SynthDefs to an NRT server is to use SynthDef: -writeDefFile to avoid this problem. This works by writing the SynthDef into the default SynthDef directory; then, the NRT server reads SynthDefs from the default location when it starts up. This approach is perfectly valid, but has the disadvantage of leaving .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.

Examples

Algorithmic generation of Synth messages

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.

NRT processing of an audio file

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.

Generating NRT scores from patterns

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.

Analysis using a Non-Realtime server

An NRT server may also be used to extract analytical data from a sound file. The main issues are:

Suppressing audio file output
In macOS and Linux environments, use /dev/null for the output file path. In Windows, use NUL.
Retrieving analytical data.
The easiest way is to allocate a buffer at the beginning of the NRT score, and use BufWr to fill the buffer. At the end of the score, write the buffer into a temporary file. Then you can use SoundFile on the language side to access the data. See the example.

OSC file format

If, for some reason, you need to write the OSC command file yourself without using Score, the general method is:

  1. Open a file for writing: File(path, "w").
  2. For each OSC command:
    1. Create the command as an array, and save it in a variable such as cmd.
    2. Convert to binary: cmd = cmd.asRawOSC;
    3. Write the byte size as an integer: file.write(cmd.size);
    4. Write the binary command: file.write(cmd);

Bus allocation and synth/LFO mapping

In this example, a control bus and LFO map is used to have various affects on the source sound.

helpfile source: https://github.com/supercollider/supercollider/tree/3.13/HelpSource/Guides/Non-Realtime-Synthesis.schelp
link::Guides/Non-Realtime-Synthesis::