BaseModule API¶

Here are the explanations about the processing class under every cecilia module.

Declaration of the module’s class¶

Every module must contain a class named ‘Module’, where the audio processing will be developed. In order to work properly inside the environment, this class must inherit from the BaseModule class, defined inside the Cecilia source code. The BaseModule’s internals create all links between the interface and the module’s processing. A Cecilia module must be declared like this:

class Module(BaseModule):
    '''
    Module's documentation
    '''
    def __init__(self):
        BaseModule.__init__(self)
        ### Here comes the processing chain...

The module file will be executed in an environment where both BaseModule and pyo are already available. No need to import anything specific to define the audio process of the module.

Module’s output¶

The last object of the processing chain (ie the one producing the output sound) must be called ‘self.out’. The audio server gets the sound from this variable and sends it to the Post-Processing plugins and from there, to the soundcard.

Here is an example of a typical output variable, where ‘self.snd’ is the dry sound and ‘self.dsp’ is the processed sound. ‘self.drywet’ is a mixing slider and ‘self.env’ is the overall gain from a grapher’s line:

self.out = Interp(self.snd, self.dsp, self.drywet, mul=self.env)

Module’s documentation¶

The class should provide a __doc__ string giving relevant information about the processing implemented by the module. The user can show the documentation by selecting ‘Help Menu’ —> ‘Show Module Info’. Here is an example:

'''
"Convolution brickwall lowpass/highpass/bandpass/bandstop filter"

Description

Convolution filter with a user-defined length sinc kernel. This
kind of filters are very CPU expensive but can give quite good
stopband attenuation.

Sliders

    # Cutoff Frequency :
        Cutoff frequency, in Hz, of the filter.
    # Bandwidth :
        Bandwith, in Hz, of the filter.
        Used only by bandpass and pnadstop filters.
    # Filter Order :
        Number of points of the filter kernel. A longer kernel means
        a sharper attenuation (and a higher CPU cost). This value is
        only available at initialization time.

Graph Only

    # Overall Amplitude :
        The amplitude curve applied on the total duration of the performance

Popups & Toggles

    # Filter Type :
        Type of the filter (lowpass, highpass, bandpass, bandstop)
    # Balance :
        Compression mode. Off, balanced with a fixed signal
        or balanced with the input source.
    # Polyphony Voices :
        Number of voices played simultaneously (polyphony),
        only available at initialization time
    # Polyphony Spread :
        Pitch variation between voices (chorus),
        only available at initialization time

'''

Public Attributes¶

These are the attributes, defined in the BaseModule class, available to the user to help in the design of his custom modules.

self.sr: Cecilia’s current sampling rate.
self.nchnls: Cecilia’s current number of channels.
self.totalTime: Cecilia’s current duration.
self.filepath: Path to the directory where is saved the current cecilia file.
self.number_of_voices: Number of voices from the cpoly widget.
self.polyphony_spread: List of transposition factors from the cpoly widget.
self.polyphony_scaling: Amplitude value according to polyphony number of voices.

Public Methods¶

These are the methods, defined in the BaseModule class, available to the user to help in the design of his custom modules.

self.addFilein(name): Creates a SndTable object from the name of a cfilein widget.
self.addSampler(name, pitch, amp): Creates a sampler/looper from the name of a csampler widget.
self.getSamplerDur(name): Returns the duration of the sound used by the sampler name.
self.duplicate(seq, num): Duplicates elements in a sequence according to the num parameter.
self.setGlobalSeed(x): Sets the Server’s global seed used by objects from the random family.

Template¶

This template, saved in a file with the extension ‘.c5’, created a basic module where a sound can be load in a sampler for reading, with optional polyphonic playback. A graph envelope modulates the amplitude of the sound over the performance duration.

class Module(BaseModule):
    '''
    Module's documentation
    '''
    def __init__(self):
        BaseModule.__init__(self)
        ### get the sound from a sampler/looper
        self.snd = self.addSampler('snd')
        ### mix the channels and apply the envelope from the graph
        self.out = Mix(self.snd, voices=self.nchnls, mul=self.env)

Interface = [
    csampler(name='snd'),
    cgraph(name='env', label='Amplitude', func=[(0,1),(1,1)], col='blue1'),
    cpoly()
]