Reusing code in multiple SynthDefs

[dayunbao]

I'm in the process of implementing phase modulation operators based on sclang examples provided by someone in the SuperCollider forums. Here's the code, for reference:

Without feedback:

(
var onepoleLP = { |sig, freq|
	var nyquist = SampleRate.ir / 2;
	var freqClipped = freq.clip(nyquist.neg, nyquist);
	var slope = freqClipped.abs * SampleDur.ir;
	OnePole.ar(sig, exp(-2pi * slope));
};

var operatorPM = { |reset, freq, mod = 0|
	var phase = Phasor.ar(reset, freq * SampleDur.ir);
	SinOsc.ar(DC.ar(0), phase + mod * 2pi);
};

var operatorStack = { |reset, carrFreq, modRatio, pmIndex|
	var modFreq = carrFreq * modRatio;
	var modulator = operatorPM.(reset, modFreq) / 2pi * pmIndex;
	modulator = onepoleLP.(modulator, modFreq);
	operatorPM.(reset, carrFreq, modulator);
};

{
	var reset;
	var parallel, stack_A, stack_B;
	reset = \reset.tr(0);
	stack_A = operatorStack.(reset, \carrFreq_A.kr(100), \modRatio_A.kr(1.5), \pmIndex_A.kr(2.5));
	stack_B = operatorStack.(reset, \carrFreq_B.kr(200), \modRatio_B.kr(2.0), \pmIndex_B.kr(1.0));
	parallel = [stack_A, stack_B].sum;
}.plot(0.021);
)

With feedback:

s.options.blockSize = 1;

(
var onepoleLP = { |sig, freq|
	var nyquist = SampleRate.ir / 2;
	var freqClipped = freq.clip(nyquist.neg, nyquist);
	var slope = freqClipped.abs * SampleDur.ir;
	OnePole.ar(sig, exp(-2pi * slope));
};

var operatorPM = { |reset, freq, mod = 0|
	var phase = Phasor.ar(reset, freq * SampleDur.ir);
	SinOsc.ar(DC.ar(0), phase + mod * 2pi);
};

var operatorFb = { |reset, freq, fbIndex|
	var fbIn, sig, mod;
	fbIn = LocalIn.ar(1);
	mod = fbIn * fbIndex;
	mod = onepoleLP.(mod, freq);
	sig = operatorPM.(reset, freq, mod);
	LocalOut.ar(sig);
	sig;
};

{
	var reset = \reset.tr(0);
	operatorFb.(reset, \carrFreq_A.kr(100), \fbIndex.kr(1));
}.plot(0.021);
)

My question relates to the best way to do something like the onepoleLP and operatorPM functions used.

I've already made version of the above in Supriya. Here they are.

Without feedback:

@synthdef()
def phase_modulation_operator(
    amplitude=0.2,
    carrier_adsr=(0.01, 0.3, 0.5, 3.0),
    carrier_curve=(-4),
    carrier_frequency=440,
    carrier_phase_index=1.0,
    carrier_ratio=1,
    gate=1,
    modulator_adsr=(0.01, 0.3, 0.5, 3.0),
    modulator_curve=(-4),
    modulator_ratio=1,
    modulator_phase_index=1.0,
):
    carrier_envelope = EnvGen.kr(
        envelope=Envelope.adsr(
            attack_time=carrier_adsr[0],
            decay_time=carrier_adsr[1], 
            sustain=carrier_adsr[2],
            release_time=carrier_adsr[3],
            curve=carrier_curve[0],
        ),
        done_action=2,
        gate=gate,
    )

    modulator_envelope = EnvGen.kr(
        envelope=Envelope.adsr(
            attack_time=modulator_adsr[0],
            decay_time=modulator_adsr[1], 
            sustain=modulator_adsr[2],
            release_time=modulator_adsr[3],
            curve=modulator_curve[0],
        ),
        done_action=2,
        gate=gate,
    )
    ratio = IRand.ir(minimum=1, maximum=3)
    carrier_ratio = ratio
    modulator_ratio = ratio * 2

    modulator_frequency = carrier_frequency * modulator_ratio
    carrier_frequency *= carrier_ratio

    # Modulator
    phase = Phasor.ar(trigger=0, rate=modulator_frequency * SampleDur.ir())
    modulator = SinOsc.ar(frequency=DC.ar(source=0), phase=phase) / (TWO_PI * modulator_phase_index) * modulator_envelope

    nyquist = SampleRate.ir() / 2
    clipped_frequency = modulator_frequency.clip(-nyquist, nyquist)
    slope = abs(clipped_frequency) * SampleDur.ir()
    modulator = OnePole.ar(source=modulator, coefficient=(-TWO_PI * slope).exponential())
    
    # Carrier
    phase = Phasor.ar(trigger=0, rate=carrier_frequency * SampleDur.ir())
    carrier = SinOsc.ar(frequency=DC.ar(source=0), phase=(phase + modulator) * TWO_PI * carrier_phase_index) * carrier_envelope

    pan = Pan2.ar(source=carrier, position=0.0, level=amplitude)
    Out.ar(bus=0, source=pan)

With feedback:

@synthdef()
def feedback_phase_modulation_operator(
    adsr=(0.01, 0.3, 0.5, 3.0),
    amplitude=0.2,
    curve=(-4),
    frequency=440,
    feedback_index=1.0,
    gate=1,
):
    envelope = EnvGen.kr(
        envelope=Envelope.adsr(
            attack_time=adsr[0],
            decay_time=adsr[1], 
            sustain=adsr[2],
            release_time=adsr[3],
            curve=curve[0],
        ),
        done_action=2,
        gate=gate,
    )

    feedback = LocalIn.ar(channel_count=1) * feedback_index

    # OnePole
    nyquist = SampleRate.ir() / 2
    clipped_frequency = frequency.clip(-nyquist, nyquist)
    slope = abs(clipped_frequency) * SampleDur.ir()
    modulator = OnePole.ar(source=feedback, coefficient=(-TWO_PI * slope).exponential())

    # Operator PM
    phase = Phasor.ar(trigger=0, rate=frequency * SampleDur.ir())
    carrier = SinOsc.ar(frequency=DC.ar(source=0), phase=(phase + modulator) * TWO_PI)
    LocalOut.ar(source=carrier)

    carrier *= envelope

    pan = Pan2.ar(source=carrier, position=0.0, level=amplitude)
    Out.ar(bus=0, source=pan)

I want to create some algorithms (operators in specific arrangements) using the above code. I previously did this for frequency modulation operators by making one SynthDef per algorithm. That meant creating 4 operators per SynthDef rather than having a generic SynthDef for an operator and using that over and over again. This resulted in a lot of duplicate code, but it didn't seem like there was a better way to do it. However, now I'm wondering if there's a way to encapsulate this block of code, for example:

nyquist = SampleRate.ir() / 2
clipped_frequency = frequency.clip(-nyquist, nyquist)
slope = abs(clipped_frequency) * SampleDur.ir()
modulator = OnePole.ar(source=feedback, coefficient=(-TWO_PI * slope).exponential())

so I can reuse it. Other wise I'll need to copy and paste that code block three to four times per SynthDef. Would creating a pseudo-UGen be the best way? If so, is there a place in the Supriya repo I could look for an example of how to do that?

[josephine-wolf-oberholtzer]

You have three two and a half options:

• Write a "pseudo ugen"
• Just write a function that returns a UGenOperable
• Stop using @synthdef and start using SynthDefBuilder so you can re-use it in function calls (more advanced)

There are a handful of pseudo ugens adapted from sclang. You can find them in the codebase by searching for PseudoUGen:

• supriya/supriya/ugens/filters.py

  Line 99 in 1187c91

  class Changed(PseudoUGen):

• supriya/supriya/ugens/dynamics.py

  Line 43 in 1187c91

  class CompanderD(PseudoUGen):

• supriya/supriya/ugens/lines.py

  Line 137 in 1187c91

  class LinLin(PseudoUGen):

Personally, I think these are awkward and tend to confuse people because they look like UGens from a user-facing perspective, but are just function calls.

Writing LinLin as a function looks something like this:

from supriya.ugens import Mix, UGenOperable
from supriya.ugens.core import UGenRecursiveInput

def linlin(
    source: UGenRecursiveInput,
    input_minimum: UGenRecursiveInput = 0.0,
    input_maximum: UGenRecursiveInput = 1.0,
    output_minimum: UGenRecursiveInput = 1.0,
    output_maximum: UGenRecursiveInput = 2.0,
) -> UGenOperable:
    scale = (output_maximum - output_minimum) / (input_maximum - input_minimum)
    offset = output_minimum - (scale * input_minimum)
    return MulAdd.new(source=source, multiplier=scale, addend=offset)

^ You can use a function like that inside a @synthdef block and it should work because everything inside that block gets called inside a SynthDefBuilder context.

[dayunbao]

Oh, perfect. That last example was exactly what I was looking for. Thanks so much!

[josephine-wolf-oberholtzer]

This is kind of advanced, but there's a SynthDefFactory class which allows configuring an algorithm for building a SynthDef. At the guts of it, there's a build() method that creates a SynthDefBuilder and passes it to a series of function calls:

supriya/supriya/ugens/factories.py

Lines 363 to 381 in 1187c91

	def build(self, name=None, **kwargs):
	"""
	Build the SynthDef.
	"""
	builder = SynthDefBuilder()
	state = self._initial_state.copy()
	with builder:
	state.update(**kwargs)
	self._setup_parameters_and_state(builder, state, kwargs)
	source = self._build_input(builder, state)
	source = self._build_feedback_loop_input(builder, source, state)
	for signal_block in self._signal_blocks:
	source = signal_block(builder, source, state)
	if source is not None and not isinstance(source, Sequence):
	source = UGenVector(source)
	self._build_output(builder, source, state)
	self._build_feedback_loop_output(builder, source, state)
	self._build_silence_detection(builder, source, state)
	return builder.build(name=name)

You can do similar if you want to really set up a library of composable synthdef-building functions.

[dayunbao]

I was just looking at that. I definitely want to spend some time checking that out. Thanks!