r
project name: r
project url: https://github.com/antonhornquist/r
author: jah
description: general purpose audio patching engine
tags: lib

R

General purpose audio patching engine

Features

Disclaimer

Commands

* In an earlier version inputs were referred to with the same delimiter as outputs <modulename/input>. This still works but is deprecated. For clarity, it is advised to use the new delimiter <modulename*input>.

Bulk Commands

Macro Commands

Polls

The engine has ten polls named poll1 to poll10. Snapshots of module output signals can be routed to these polls. In addition, some modules expose feedback values typically used for visualization (ie. the MMFilter module feedback value Frequency which takes frequency modulation into account). These values - referred to as visuals - can also be routed to the polls.

Only one output or visual can be routed to each poll at any given time. The latest routed output or visual takes precedence.

Debug Commands

Modules

44Matrix

4x4 matrix signal router.

88Matrix

8x8 matrix signal router.

ADSREnv

ADSR Envelope.

Amp

Simple amplifier with level parameter and exponential or linear gain modulation.

Amp2

Amplifier with two inputs, level parameter and variable exponential or linear gain modulation.

BPFilter

Resonant bandpass SVF filter.

BRFilter

Resonant bandreject (Notch) SVF filter.

DbMixer

Mixer suited for audio signals.

Delay

Delay line.

EQBP

Non-resonant, variable width bandpass filter.

FShift

Frequency shifter.

FreqGate

CV/Gate like thing.

HPFilter

Resonant highpass SVF filter.

LPFilter

Resonant lowpass SVF filter.

LPLadder

Lowpass ladder filter.

LinMixer

Mixer suited for control signals.

MGain

Audio fader with db gain control and mute.

MMFilter

Resonant SVF multimode filter.

MultiLFO

LFO featuring multiple waveforms.

MultiOsc

Oscillator featuring multiple waveforms.

Noise

White noise generator.

OGain

8-in/8-out audio fader with db gain control and mute.

PNoise

Pink noise generator.

PShift

Pitch shifter.

Pan

Stereo panner with monophonic input.

PulseOsc

Pulse/square oscillator with pulse width control.

QGain

4-in/4-out audio fader with db gain control and mute.

RingMod

Ring modulator.

SGain

2-in/2-out audio fader with db gain control and mute.

SampHold

Sample and hold module.

SawOsc

Sawtooth oscillator.

SineLFO

Sine LFO

SineOsc

Sine oscillator

Slew

Slew rate limiter.

SoundIn

Stereo sound input

SoundOut

Stereo sound output

TestGen

Test sound generator.

TriOsc

Triangle oscillator (non-bandlimited).

XFader

Crossfader.

Example Usage

-- Spawn three modules
engine.new("LFO", "MultiLFO")
engine.new("Osc", "PulseOsc")
engine.new("SoundOut", "SoundOut")

-- Modulate OSC pulse width by LFO sine wave
engine.connect("LFO/Sine", "Osc*PWM")

-- Hook up oscillator to audio outputs
engine.connect("Osc/Out", "SoundOut*Left")
engine.connect("Osc/Out", "SoundOut*Right")

-- Set module parameter values
engine.set("Osc.PulseWidth", 0.25)
engine.set("LFO.Frequency", 0.5)
engine.set("Osc.PWM", 0.2)

See tutorial scripts in r_tuts and roar scripts moln, rymd, bob and skev for more elaborate examples.

The R Lua Module

The R Lua module contains:

Require the R module:

local R = require 'r/lib/r'

Module Specs

R.specs contains default specs for all modules, ie.:

R.specs.MultiOsc.Tune -- returns ControlSpec.new(-600, 600, "linear", 0, 0, "cents")

These can be copied and overriden, if needed:

local my_testgen_spec = R.specs.TestGen.Frequency:copy() -- returns ControlSpec.WIDEFREQ
my_testgen_spec.minval = 80
my_testgen_spec.maxval = 8000

Engine Functions

R.engine.poly_new("Osc", "MultiOsc", 3) -- creates MultiOsc modules Osc1, Osc2 and Osc3
R.engine.poly_new("Filter", "MMFilter", 3) -- creates MMFilter modules Filter1, Filter2 and Filter3

R.engine.poly_connect("Osc/Saw", "Filter*In", 3) -- connects Osc1/Saw to Filter1*In, Osc2/Saw to Filter2*In and Osc3/Saw to Filter3*In

Utility Functions

R.util.split_ref("Osc.Frequency") -- returns {"Osc", "Frequency"}
R.util.poly_expand("Osc", 3) -- returns "Osc1 Osc2 Osc3"

Considerations

Extending R

TODO: new approach used

Modules are written by way of subclassing the RModule class. A subclass supplies a unique module type name (by overriding *shortName), an array of specs for each module parameter (*params) and a SynthDef Ugen Graph function (*ugenGraphFunc) whose function arguments prefixed with param_, in_ and out_ are treated as parameter controls and input and output busses. The R engine will introspect the ugenGraphFunc and together with the parameter specs provide scaffolding necessary to supply parameter values and interconnect modules.

Note: If a dictionary is supplied for a parameter in the *params array, its Spec key value will be used as spec and its LagTime value will be used as fixed lag rate for the parameter. Annotated example:

RTestModule : RModule { // subclassing RModule makes this a module

	*shortName { ^'Test' } // module type used in engine new command

	*params { // description of the module parameters
		^[
			'Frequency' -> \widefreq.asSpec, // first parameter
			'FrequencyModulation' -> (
				Spec: \unipolar.asSpec, // second parameter
				LagTime: 0.05 // 50 ms lag
			)
		]
	}

	*ugenGraphFunc { // regular SynthDef ugenGraphFunc function describing DSP
		^{
			|
				in_FM, // will reference a bus to be used for audio input
				out_Out, // will reference a bus to be used for audio output
				param_Frequency, // refer to first parameter's value...
				param_FrequencyModulation // ... and second parameter's value
			|

			var sig_FM = In.ar(in_FM);
			var sig = SinOsc.ar(param_Frequency + (1000 * sig_FM * param_FrequencyModulation)); // linear FM
			Out.ar(out_Out, sig);
		}
	}

}

Updating the R Lua module

To be usable with functions in the R Lua module R.engine table module parameter metadata has to be included in the R.specs table. R.specs can be generated in SuperCollider from RModule metadata using the Engine_R.generateLuaSpecs method. TODO: new variant used

Module documentation stubs may be generated in SuperCollider using the Rrrr.generateModulesDocSection method. TODO: new variant used

Gotchas

If one of the parameters of a module has a ControlSpec not compatible with Lag (ie. the standard db ControlSpec) lag time should not be used for any of the parameters. This is a known SuperCollider issue. (TODO: describe workaround)

Status