LevelComp | SuperCollider 3.14.0-dev Help

Description

Mixing and Panning multichannel signals often requires Level Compensation when Mixing and Panning. LevelComp provides a logic for this that is used internally in the Splay and SplayAz UGens. Using the levelComp argument of Splay/Az, it calculates a level compensation factor applied to the input signals, depending on the number of input channels.

Class Methods

LevelComp.new(levelComp, rate, n)

Calculate a scaling factor based on the levelComp argument and the number of channels to be mixed.

Arguments:

levelComp

a flag or numeric value:

true : equal power level compensation (default)
false : off / no level change,
float between 0.0 and 1.0 : smooth tuning of levelComp factor:
- 0.0 is none -> factor 1
- 0.5 is equal power -> factor (1/n).squared
- 1.0 is equal amplitude -> factor (1/n)

rate

the rate for which to calculate - \audio or \control.

the number of channels being mixed and scaled.

Returns:

the levelComp factor by which to multiply the output signals.

Inherited class methods

Instance Methods

Inherited instance methods

Examples

Splay and SplayAz use LevelComp internally via the levelComp argument, and obtain rate and number of channels from Splay/Az.

Here is an Overview of the levelComp usage variants:

Discussion and demonstration of level compensation options:

We begin testing with equal power compensation: how much too high can the summed levels rise for different numbers of channel to mix/pan with Splay?

s.meter;
s.scope;

// synthesize 2 test signals at level 0.1 (-20 dB), first on separate channels
(
{ var n = 2, level = 0.1, spread = 1, pan = 0;
    LFPulse.ar({ 100.exprand(2000) } ! n).range(-1, 1) * level
}.play;
)

// now mix/pan these 2 signals using Splay, level at 0.1 (-20dB)
(
x = { |spread = 1, level = 0.1, center = 0|
    var n = 2;
    var snd = LFPulse.ar({ 100.exprand(2000) } ! n).range(-1, 1);
    var stereo = Splay.ar(snd, spread, level, center);
    Peak.ar(stereo, Impulse.kr(2)).ampdb.poll(2);
    stereo
}.play;
)

// when we set full spread, panned to center:
// the 2 signals are discrete, left and right
// we see the energy-based levelComp applied (1/2.sqrt).ampdb = -3
x.set(\spread, 1, \center, 0); // -20 - 3 = -23dB

// no spread, panned center:
// each signal decreases by 3dB as they move to the center (from the panning function)
// and the two signals mix on each channel, so we get -20 dB
x.set(\spread, 0, \center, 0); //  -20dB

// no spread, panned fully right:
// the signals fully mix in the right channel (+6 dB)
x.set(\spread, 0, \center, 1); // -23 + 6 = -17db

Trying the same example with 20 channels and with equal power compensation, (which we get with levelComp true), we see that the resulting sum levels are much higher:

Finally, here are the theoretical worst cases for 20, 200, and 2000 channels, with equal power: 13, 23 and 33 db louder!

So for maximum peak safety, use levelComp: 1 (or equivalently, set levelComp: false, and explicitly set level to 1/n, i.e. divide by the number of channels for amplitude compensation).

Then the levels predictably remain the same, independent of the number of channels to be mixed.

{ n = 2; Splay.ar(DC.ar(1!n), 1, 1, 0, levelComp: 1).ampdb.poll }.plot; // -6 db on both
{ n = 2; Splay.ar(DC.ar(1!n), 1, 1/n, 0, levelComp: false).ampdb.poll }.plot;
{ n = 2; Splay.ar(DC.ar(1!n), 0, 1, 0, levelComp: 1).ampdb.poll }.plot; // -3 db on both
{ n = 2; Splay.ar(DC.ar(1!n), 0, 1, 0.99, levelComp: 1).ampdb.poll }.plot; // 0 db

// these are now the same for all tested values of n:
{ n = 20; Splay.ar(DC.ar(1!n), 1, 1, 0, levelComp: 1).ampdb.poll }.plot; // -4 db
{ n = 20; Splay.ar(DC.ar(1!n), 0, 1, 0, levelComp: 1).ampdb.poll }.plot; // -3 db
{ n = 20; Splay.ar(DC.ar(1!n), 0, 1, 0.99, levelComp: 1).ampdb.poll }.plot; // 0 db on right

{ n = 200; Splay.ar(DC.ar(1!n), 1, 1, 0, levelComp: 1).ampdb.poll }.plot; // -4 db
{ n = 200; Splay.ar(DC.ar(1!n), 0, 1, 0, levelComp: 1).ampdb.poll }.plot; // -3 db
{ n = 200; Splay.ar(DC.ar(1!n), 0, 1, 0.99, levelComp: 1).ampdb.poll }.plot; // 0 db on right

{ n = 2000; Splay.ar(DC.ar(1!n), 1, 1, 0, levelComp: 1).ampdb.poll }.plot; // -4 db
{ n = 2000; Splay.ar(DC.ar(1!n), 0, 1, 0, levelComp: 1).ampdb.poll }.plot; // -3 db
{ n = 2000; Splay.ar(DC.ar(1!n), 0, 1, 0.99, levelComp: 1).ampdb.poll }.plot; // 0 db on right

helpfile source: /usr/local/share/SuperCollider/HelpSource/Classes/LevelComp.schelp
link::Classes/LevelComp::

LevelComp : Object