uRTcmix Tutorial

installing the uRTcmix package

Note: If you are installing [rtcmix~] on macOS machines running Catalina (10.15.x) or later, you will probably get the Apple 'gatekeeper' message about the library/application not able to run because it isn't from a 'signed developer'. One of these days We'll wade through the impenetrable documentation about how to do this, but for now you can follow the instructions here to get it going.

libs/ -- this contains the loadable lib files for RTcmix to run

prefabs/ -- this contains two 'prefabs' beep.prefab and RTcmixmain.prefab. Their use is explained below.

scripts/ -- this contains the C# source code for the beep prefab and the RTcmixmain prefab. The rtcmixmain script contains the C# definitions of all the usaable uRTcmix functions. The uRTcmixScriptTemplate C# script shows how the uRTcmix functions can be used. Most of them are commented-out because you will use them only for specific purposes.

"Unsafe code requires the `unsafe' command line option to be specified. Enable "Allow 'unsafe' code" in Player Settings to fix this error."

make a beep

The rtcmixmain RTcmix; statement declares a variable that we will use to access the RTcmix functions from the RTcmixmain object.

The private bool did_start = false; statement declares a boolean (true/false) variable, did_start; and sets it initially to "false". This is so that the "beep" script won't try to run audio until RTcmix is initialized. The objno, RTcmix and did_start variables are declared here at the top of the class definition, within the "beep" class but outside any of the "beep" methods because they will be used throught the entire "beep" class.

Next we add a new method, Awake() and a new line of code to the Start() method:

	private void Awake()
	{
		// find the RTcmixmain object with the RTcmix function definitions
		RTcmix = GameObject.Find("RTcmixmain").GetComponent<rtcmixmain>();
	}

	// Use this for initialization
	void Start () {
		RTcmix.initRTcmix (objno);

Once we have made that connection, we can use the RTcmix variable to invoke the functions defined in the "rtcmixmain.cs" script. We do this in the very first line of the Start() method: RTcmix.initRTcmix (objno); to initialize the RTcmix process for the objno we want to use (in this case, "0").

We then add a single line to our Start() ethod that will send a very simple (one line!) script to RTcmix:

	RTcmix.SendScore("WAVETABLE(0, 8.7, 20000, 8.07, 0.5)", objno);

This sends the String (the score) in the double-quotes to RTcmix for parsing and execution. The final parameter, objno, does what it did in the RTcmix.initRTcmix (objno) case; it designates which RTcmix process to use.

Finally, because we have now fully initialized RTcmix, we set did_start = true; to allow audio processing in this script to take place.

Our finished Start() method then looks like this:

	// Use this for initialization
	void Start () {
		// initialize RTcmix
		RTcmix.initRTcmix (objno);

		// send a note using the WAVETABLE() instrument
		RTcmix.SendScore("WAVETABLE(0, 8.7, 20000, 8.07, 0.5)", objno);

		did_start = true;
	}

But you will need to add two additional methods to the "beep" class for this to work:

	void OnAudioFilterRead(float[] data, int channels)
	{
		if (!did_start) return;

		// compute sound samples
		RTcmix.runRTcmix(data, objno, 0);
	}


	void OnApplicationQuit()
	{
		did_start = false;
		RTcmix = null;
	}

The OnAudioFilterRead() method passes audio data to and from the "beep" class through the data array parameter. We hand that off to RTcmix with the RTcmix.runRTcmix (data, objno, 0); line, invoking the runRTcmix() method from the "rtcmixmain.cs" file. runRTcmix() will fill the data array with one buffers-worth of sound samples from the RTcmix process (usually 512 samples in Unity). Note the use of objno again.

The final "0" after the objno variable signals that we are only synthesizing sound, not processing any sound that comes into the 'beep' class from a previous sound-generating object in Unity. A final "1" in the RTcmix.runRTcmix() would allow us to do input signal-processing. We will discuss this later.

The OnApplicationQuit() method resets RTcmix by destroying the particular instantiation and setting did_start to "false" so that the next time we run the scene (and the Start() method is called), everything will be set up properly.

Our final "beep.cs" file looks like this:

using System.Collections;
using System.Collections.Generic;
using UnityEngine;


// a very simple script to make a G-above-middle-C 'beep' on startup

public class beep : MonoBehaviour {
	int objno = 0;
	rtcmixmain RTcmix;
	private bool did_start = false;


	private void Awake()
	{
		// find the RTcmixmain object with the RTcmix function definitions
		RTcmix = GameObject.Find("RTcmixmain").GetComponent<rtcmixmain>();
	}


	// Use this for initialization
	void Start ()
	{
		// initialize RTcmix
		RTcmix.initRTcmix(objno);

		// send a note using the WAVETABLE() instrument
		RTcmix.SendScore("WAVETABLE(0, 8.7, 20000, 8.07, 0.5)", objno);

		did_start = true;
	}


	// Update is called once per frame
	void Update ()
	{
	}


	void OnAudioFilterRead(float[] data, int channels)
	{
		if (!did_start) return;

		// compute sound samples
		RTcmix.runRTcmix(data, objno, 0);
	}


	void OnApplicationQuit()
	{
		did_start = false;
		RTcmix = null;
	}
}

beeping...

This requires only two alterations in our original "beep" script. One is to the initial RTcmix.SendScore() score that we send to include a MAXBANG() scheduled 'bang' in the future, and one to detect when that 'bang' occurs and respond appropriately.

Our revised Start() method looks like this:

	// Use this for initialization
	void Start ()
	{
		// initialize RTcmix
		RTcmix.initRTcmix(objno);

		// send a note using the WAVETABLE() instrument
		RTcmix.SendScore("WAVETABLE(0, 0.2, 20000, 8.07, 0.5)  MAXBANG(0.3)", objno);

		did_start = true;
	}

We will detect that MAXBANG()-scheduled 'bang' within the OnAudioFilterRead() method. We accomplish this by using the uRTcmix function RTcmix.checkbangRTcmix(). This function will return "1" when a 'bang' is detected at a scheduled time. The OnAudioFilterRead() method now looks like this:

	void OnAudioFilterRead(float[] data, int channels)
	{
	  RTcmix.runRTcmix (data, objno, 0);

		if (RTcmix.checkbangRTcmix (objno) == 1) {
			RTcmix.SendScore("WAVETABLE(0, 0.2, 20000, 8.07, 0.5)  MAXBANG(0.3)", objno);
		}
	}

If we add the file "granular.txt" containing the RTcmix code above to our Unity assets, we can edit it the same way we edit C# scripts that work as assets in Unity. To access the RTcmix code in the file in our game object script, you can take advantage of the Unity/C# "TextAsset" class.

Essentially, you declare a public variable that will 'hold' your TextAsset scorefile, and you can then extract a string from that TextAsset for use by the RTcmix.SendScore() method. Here is how to set it up:

using UnityEngine;
using System.Collections;
using System; // this is necessary for String operations

public class granularize : MonoBehaviour {
	int objno = 0;
	rtcmixmain RTcmix;
	private bool did_start = false;

	public TextAsset grantextfile;
	String granscore;

	private void Awake()
	{
		// find the RTcmixmain object with the RTcmix function definitions
		RTcmix = GameObject.Find("RTcmixmain").GetComponent<rtcmixmain>();
	}


	// Use this for initialization
	void Start () {
		RTcmix.initRTcmix (objno);

		granscore = grantextfile.text;

		...

alter a beep

In the 'beep' class, we will use another variable, frequency, declared globally (at the top of the class definition) to set the frequency of the repeating WAVETABLE() RTcmix instrument. Our setup now looks like this:

using UnityEngine;
using System.Collections;
using System;


public class beep : MonoBehaviour {
	int objno = 0;
	rtcmixmain RTcmix;
	private bool did_start = false;

	float frequency;

	private void Awake()
	{
		// find the RTcmixmain object with the RTcmix function definitions
		RTcmix = GameObject.Find("RTcmixmain").GetComponent<rtcmixmain>();
	}


	// Use this for initialization
	void Start () {
		// initialize RTcmix
		RTcmix.initRTcmix (objno);

		RTcmix.SendScore("freqval = makeconnection(\"inlet\", 1, 700.0)  " +
			"WAVETABLE(0, 99999, 20000, freqval, 0.5)", objno);

		frequency = 700.0f;

		did_start = true;
	}

The WAVETABLE() is started with a duration of "99999" -- this is just to insure that the note continues to play so that we may alter the frequency when we want. That value is arbitrary, and if 99999 seconds is too short it can be extended.

Next we add script code to the "beep" class definition to alter the value of the frequency variable. We do this in our Update() method by seeing if the user has typed an Up or Down arrow:

	// Update is called once per frame
	void Update () {
		if (Input.GetKey (KeyCode.UpArrow)) {
			frequency = frequency + 10.0f;
		}
		if (Input.GetKey (KeyCode.DownArrow)) {
			frequency = frequency - 10.0f;
		}

		RTcmix.setpfieldRTcmix (1, frequency, objno);
	}

This will work, but it's not the most efficient way of doing the task. The Update() method will be called at the frame rate of Unity, usually 60 times/second. We only need to update our WAVETABLE() frequency value when the user presses one of the arrow keys -- probably not 60 times/second. A better approach would be this:

	// Update is called once per frame
	void Update () {
		if (Input.anyKey) {
			if (Input.GetKey (KeyCode.UpArrow)) {
				frequency = frequency + 10.0f;
			}
			if (Input.GetKey (KeyCode.DownArrow)) {
				frequency = frequency - 10.0f;
			}

			RTcmix.setpfieldRTcmix (1, frequency, objno);
		}
	}

modifying RTcmix scorefiles

To take advantage of this capability, the RTcmix score needs to include special variables with a"$" as the first character and a number as the second (this is also from the [rtcmix~] object in Max/MSP). The "$" signals that this variable needs to have a value assigned from "outside" RTcmix, and the number indicates the ordering of the assignments.

For example, the small RTcmix score:

WAVETABLE(0, 7, $1, $2)

Let's look at a modified version of the RTcmix code in the "granular.txt" example from above to show how these $variables work:

reset(44100)
hifreq = $1
lowfreq = $2

amp = 15000
ampenv = maketable("window", 1000, "hanning")

start = 0
dur = 0.05
for (i = 0; i < 20; i = i+1) {
	freq = irand(hifreq, lowfreq)
	WAVETABLE(start, dur, amp*ampenv, freq)
	start = start + (dur/2)
}

MAXBANG(start)

If we took the granular synthesis score above with the $variables set for hifreq and lowfreq and put it in our "granular.txt" file, we can do this substitution with the following code:

	(...)

	public TextAsset grantextfile;
	String granscore;

	// Use this for initialization
	void Start () {
		(...)

		granscore = grantextfile.text; // assumes that "grantextfile" has been set to the "granular.txt" scorefile

		String granscore2 = RTcmix.setscorevalsRTcmix (granscore, 900.0f, 500.0f);

		// "granscore2" now has the values 900.0 and 500.0 for the "hifreq" and "lowfreq" variables
		RTcmix.SendScore (granscore2, objno);
	}

links

• Sound: Advanced Topics I (Fall 2019)
  Each week of this syllabus links to class projects and resources showing various uses of Unity and RTcmix.
  
  
• Sound: Advanced Topics I (Fall 2017)
  An older version of the previous link, with somewhat simpler projects. These use an older version of uRTcmix, but the projects should still run and the general demonstrations might be useful.
  
  
• RTcmix.org
  The main RTcmix page. Tutorials, code, useful information.