K509 — Computer Music Seminar: RTcmix Quick Reference

RTcmix Quick Reference

Just the basics. Much more detail at rtcmix.org.

NB: function arguments in [ ] are optional.

MinC Syntax

loops

for (init; test; increment) {
   // block of statements
}

e.g.,

for (start = 0; start < total_duration; start = start + time_increment) {
   // do something interesting
}

conditionals
```
if (x > 0) {	// or <, >=, <=, ==, !=
   // do something amazing
}
else if {
   // do something shocking
}
else {
   // do something terrible
}
```
You don’t need the “else” statements, but if you have several of them, the last one must be an “else,” not an “else if.”
arrays
```
myarray = { item0, item1, item2, ..., itemN-1 }
numitems = len(myarray)
```
Items can be any combination of numbers, strings (in double quotes), other arrays, or table references (like envelopes).
Write to an array element like this...
```
myarray[0] = 99.9
```
Read an array element like this...
```
myval = myarray[4]
```
Note that arrays are zero-based — that is, the index of the first element is 0; the second, 1; the last, N-1, where N is the number of items in the array. If you try to read with an index >= N, MinC returns the last item of the array. If you try to write to an index >= N, MinC expands the size of the array to accommodate the new data.
+=, -=, *=, /=
A common contraction...
```
start += increment
```
is the same as...
```
start = start + increment
```
Same for the -, *, and / operators.

Utility Functions

setup

rtsetparams(sample_rate, num_channels)

set_option("play = off")     // don't play while I'm writing a sound file

set_option("clobber = on")   // overwrite existing output file

sound files

rtinput("soundfile_name")  // must include extension, e.g., ".wav", ".aiff"

duration = DUR()    // of most recently opened input file

rtoutput("soundfile_name.wav")   // or ".aiff"

randomization

val = irand(min, max)   // returns floating-point value

val = trand(min, max)   // val is truncated (i.e., integer)

val = random()          // val is between 0 and 1

val = rand()            // val is between -1 and 1

srand(seed)             // seed is any integer

pitch conversion

freq_in_Hz = cpspch(pitch_in_oct.pc)

pitch_in_oct.pc = pchcps(freq_in_Hz)

pitch_in_oct.pc = pchmidi(midi_notenum)

pitch = pchadd(pitch1, pitch2)      // all in oct.pc

amplitude conversion

linear_amp = ampdb(dB)

dB = dbamp(linear_amp)

tables
```
table = maketable("type", [norm,] size, description)
```
where type can be: line, curve, wave, random, textfile, etc. (complete list here)
norm is either "norm" (the default) or "nonorm". This is optional.
size is number of elements in table
remaining arguments depend on type:
- for line: time0,val0, time1,val1, ..., timeN,valN
- for curve: time0,val0,curve0, time1,val1,curve1, ..., timeN,valN
  where curve=0 is linear, curve<0 is exponential, and curve>0 is logarithmic
- for wave: either a name like "saw", "tri", "square", "buzz", or
  relative partial amplitudes: p1, p2, ..., pN
- for random: type, min, max[, seed]
  where type is "linear", "low", "high", "triangle", "gaussian", or "cauchy"
- for textfile: "filename"
data streams
```
stream = makeLFO(wavetable, frequency, min, max)
```
where wavetable can be a previously defined table or a double-quoted name such as you would pass to maketable("wave"...), frequency is LFO rate in Hz, and min and max define the amplitude extremes of the waves. These last three parameters can be constants or references to tables or streams.
```
stream = makerandom(type, frequency, min, max[, seed])
```
where type is one of the random distributions listed for maketable("random"...) above, frequency is how fast the random value changes, min and max define the range of values, and seed is an optional integer seed. The frequency, min, and max parameters can be constants or references to tables or streams.
audio buses
```
bus_config("INSTRUMENT_NAME", [input_bus,] output_bus)
```
where input_bus can be "in 0-1", "aux 0 in", or "aux 0-1 in", and output_bus can be "out 0", "out 0-1", "aux 0 out", or "aux 0-1 out". There are 64 internal (aux) buses. The number of input and output buses depends on your audio hardware. For file input, the "in 0-1" tag does not let you select input channels; instead most instruments have a way of doing that, via an inchan parameter. Obviously, only instruments that process audio can have an input bus.
Instruments reading from an aux bus must have an inskip of zero. Certain instruments, like TRANS or REVMIX, cannot consume real-time input, because they might need to use audio that hasn't happened yet.

miscellaneous

load("INSTRUMENT_NAME")

control_rate(rate_in_Hz)

Instruments

Note: pan always works like this: hard left = 1, center = 0.5, hard right = 0. (Yes, this looks backwards.)

synthetic

FMINST(start, duration, peak_amp, carrier_freq, modulator_freq,
      min_modindex, max_modindex, pan, wavetable, index_guide_table)

NOISE(start, duration, peak_amp, pan)	// affected by srand()

STRUM2(start, duration, peak_amp, freq, squish, decay_time, pan)

VWAVE(start, duration, freq, peak_amp, pan, vector_guide, 
      wavetab1, wavetab2, ..., wavetabN)
      // vector synthesis using any number of wavetables
      // vector_guide is 0-1, controlling wavetable selection and
      // cross-fading

WAVETABLE(start, duration, peak_amp, freq, pan[, wavetable])

WAVY(start, duration, peak_amp, oscilA_freq, oscilB_freq,
      oscilB_phase_offset, oscilA_wavetable, oscilB_wavetable,
      expression, pan)
      // expression can be "a + b", "a - b", "a * b", etc.

processing

COMBIT(start, inskip, duration, amp_multiplier, freq, reverb_time,
      inchan, pan, ringdown_duration)   // recursive comb filter

DELAY(start, inskip, duration, amp_multiplier, delay_time, feedback,
      ringdown_duration, inchan, pan)

DISTORT(start, inskip, duration, amp_multiplier, type=1, pre_gain,
      lowpass_cf, inchan, pan, bypass)

FILTERBANK(start, inskip, duration, amp_multiplier, ringdown_duration,
      inchan, pan, cf1, bw1, gain1, cf2, bw2, gain2, ..., cfN, bwN, gainN)
      // bw is bandwidth as percent of cf, from 0 to 1

FREEVERB(start, inskip, input_duration, amp_multiplier, room_size,
      pre_delay_time, ringdown_duration, damp, dry_level, wet_level,
      stereo_width)
      // last 4 args are 0-100, room_size is 0-1.07143 (don't ask)

MULTEQ(start, inskip, duration, amp_multiplier, master_bypass,
      type1, freq1, q1, gain1, bypass1, ...,
      type2, freq2, q2, gain2, bypass2, ...,
      typeN, freqN, qN, gainN, bypassN)
      // type is "lowpass", "highpass", "lowshelf", "highshelf",
      // "peaknotch", "bandpass"

REVMIX(start, inskip, duration, amp_multiplier, inchan, pan)
      // NB: reads backwards from inskip

SHAPE(start, inskip, duration, amp_multiplier, min_distort_index,
      max_distort_index, amp_norm_table, inchan, pan,
      transfer_function_table, index_guide_table)  // waveshaping

STEREO(start, inskip, duration, amp_multiplier, pan)

TRANS(start, inskip, duration, amp_multiplier, transp_in_oct.pc,
      inchan, pan)