Program Description

Contents:

    * Program Start and General Background
          o Program Arguments
    * The Main Window
          o  Envelopes
          o  Tools for the construction of the envelopes
          o  Frequency Band / Shape of the Cloud
          o  The Waveform in the Grains
          o  The Controlpanel
          o  The Statuspanel
          o  Amplitude Envelope (ADSR) of a triggered Sound
    *  The Drehbank [MIDI Controller] Emulation
    *  Configuration
          o Configuration of the Engine
          o Configuration of the GUI - Parameters / MIDI

Program Start and General Background

Cumulus consists of 3 executables / processes which can be found in bin:

• Engine - The generic Grain Synthesis Engine
• gui - The QT User Interface which implements the Asynchronous Grain Synthesis [and the MIDI controller emulation]
• MIDIListener - The MIDI Interface for gui

They communicate with each other via UNIX sockets. The gui has to be started first because it opens the sockets and the other processes look for these. A script called start is provided which makes sure remaining sockets from previous sessions get deleted [in /tmp] and fires up the processes.

Program Arguments

The Engine and the gui take parameters:

gui [EMU]
If EMU is given, the Drehbank [MIDI controller] emulation is started

Engine [SINTAB]
If SINTAB is given, the Engine uses a sine table rather that sin() function calls to build the grains. This considerably speeds up the calculation but it needs about 30MB of RAM and worsens the sound quality.

The Main Window

If everything works fine you'll see something like this:

This is the main control window for Cumulus. If the MIDI controller emulation switch for gui is on, there will be an additional window (it may be hidden behind the main one) , see The Drehbank [MIDI Controller] Emulation .

Envelopes

For each AGS parameter there is an envelope which defines the progression in time of the parameter. The picure below shows such an envelope:

In the upper left corner you see the name of the parameter. In the white rectangle the control points can be set with the mouse: a click on the envelope selects it (the selected envelope is framed by a green rectangle), a left click into the rectangle adds a point or grabs an existing one which can be moved while the button is held down; a right click on a point removes it. The envelope is calculated through linear interpolation between these control points. The time axis is horizontal. The dimension and the value range of of the function value is dependent of the two variables Base and Range which are displayed on the right of the parameter name. The value f(t) of a point on the envelope lies in the range [0, 1], 0 is on the bottom and 1 on the top. Following formula maps the value into the desired range:

 f'(t) = Base + f(t) * Range

The values Base and Range are, like all setable numeric parameters, controlled by MIDI controllers. The mapping to certain controllernumbers and the parameter ranges are defined in the file gui.config which has to be in the same directory as gui. Because most users won't have a MIDI controller box, a simple emulator is provided which can be controlled with the mouse. Note that MIDI controllers can send values from 0 to 127.

In the line on the bottom you find the duration of the envelope in Milliseconds. This duration is fixed and is set while manipulating the envelope with the buttons Flat, Sine, Rect and Repeat (on the very bottom of the window). To manipulate the duration of the envelope all the same there is the Stretch factor. If this value is larger than 1.00 the envelope gets stretched, if it's smaller than 1.00 the envelope gets compressed. For each envelope there's an individually adjustable stretch factor as well as the possibility to use a global Master Stretch factor with which several envelopes can be stretched synchronously. On the very right is finally the duration of the stretched envelope. If the duration of a note is larger than the duration of an envelope that envelope is looped.

Tools for the construction of the envelopes

On the bottom of the Main Window on the left are 4 functions for shaping the envelopes:

On the right of each funtion, the function value is defined and with a click on the button the according action is executed:

• Flat: Deletes all points and sets the (mandatory) start and end points to the value 0.5. The time of the endpoint is set to the value in the spinbox, so the duration of the envelope can be set.
• Sine: The envelope is deleted and one period of the sine with the entered frequency is drawn. This defines the duration of the envelope.
• Rect: The envelope is deleted and a rectangle oscilation with the duration of the entered time is drawn. This defines the duration of the envelope.
• Repeat:The current envelope is added n times, with n = the entered value. The duration of the envelope is multiplied.

Frequency Band / Shape of the Cloud

The frequency band of the cloud is defined by two parameter:

• The Central Frequency
• The Frequency Width

This partitioning allows to use a MIDI-keyboard as a usefull input device: A pressed note defines the central frequency of the cloud. For this reason the value for Base of the central frequency can't be set: it's defined by the played note, using following formula:

Base = frequency of note - (Range / 2)

Note that Range depends on the frequency of the note too (see below). It means that the grey stressed line in the middle of the envelpe is exactly on the frequency of the note. Points above it let the frequency grow, points below let it fall.

Because the information density of the audio decreases exponentially with increasing frequency (one octave comprises the double frequency range of its neighbouring lower occtave) this two parameters are not defined in Hertz but relative to the frequency of the pressed note. Thus the defined sound behaves the same for high and low notes.

The Waveform in the Grains

The waveform which is filled into the Grains is always a sine of a certain frequency F which can be enichened with its harmonics. The harmonics are sine oscilations whose frequency is a whole-numbered multiple of the fundamental frequency F. The 1st harmonic has the frequency 2F, the 2nd harmonic has 3F etc.

Switches to control the Grain parameter

With the checkboxes you can select if just the even (i.e. 2F, 4F, ...), just the odd (3F, ...) or all harmonics shall be added. Additionally the behaviour of the amplitudes of the harmonics can be selected, this is if it decreases proportionaly to the number of the harmony or proportional to its square. With this, following waveforms can be built:

Waveform: | Harmonics: | Harm. Amplitute:

---

     Triangle       odd           1/sqr(harm)

Rectangle odd 1/harm

 Sawtooth       both          1/harm

Note that naturally only whole-numbered harmonics are possible. The progression of the envelope suggests a continuous transition from one value to the other, but in fact it's rounded to the next whole number.

In the left part of the panel pictured above two other parameters can be adjusted:

• Graintype: This parameter decides wich type of Grain-envelope [envelope to smooth the grain at the edges] is used. This can be

           Trapezoid                                                           Gaussian

Note: The Pictures above show the influence of the Grain Envelope Attack parameter (Attack Time).

• Grainlen: The duration of the Grains can be defined absolute (in milliseconds), relative to the period of the fundamental frequency in the Grain or randomly spread in the Interval [Base, Range + Base]

The Controlpanel

The Controlpanel consists of a number of buttons with which the Engine can be controlled and sounds can be loaded from and stored to disk.

• Clear DSP: Closes and re-opens the soundcard. I needed that because of problems with the OSS drivers in Kernel 2.0.36.
• Stop Engine: Stops the Engine but the GUI and the MIDIListener keep on running. This allows reconfiguration and restart of the Engine without loosing the current sound.
• Write to file: If switched on, the output gets written to the file /tmp/out.wav as well.

The Statuspanel

The Statuspanel shows some important information. In the upper part the value of the MasterStretch, which can be used for all envelopes, can be found. Below the coordinates of the currently selected control point are shown. The 3 green LEDs in the lower part flash red on certain [undesired] events:

• Underrun: There was a gap between 2 successive audioblocks - results in clicks, means the work was too much for the CPU [or the buffervalues are set very badly]
• Cutted: The Amplitude was too high. Reduce Amplitude or Grain Density or Grain Length.
• GrainCutted: My implementation of the Engine limits the maximum duration of a Grains. How large this is depends on the speed of CPU and the Grain Density. In the Engine-configurationfile, a limit can be set (see Configuration of the Engine). If the Engine receives a command to calculate a Grain longer than this limit, the LED flashes and the Grain is calculated with the limit duration.

Amplitude Envelope (ADSR) of a triggered Sound

Besides the parameter envelopes there is an envelope which shapes the amplitude of a triggerd sound [possibly a pressed key on the MIDI-keyboard]. This is a so called ADSR-Envelope and is usually used by synthesizers. A sound is divided in following phases:

• A - Attack Time: Defines the time from the triggering of the sound till the maximum amplitude is reached.
• D - Decay Time: After reaching the maximum, the amplitude falls to the Sustainlevel. Decaytime is the time it takes.
• S - Sustain Time: As long as the key stays pressed, the amplitude stays on the Sustainlevel. This duration is the Sustaintime.
• R - Release Time: When the key is released, the amplitude falls in Release Time to 0. This results in a fade-out.

On the Main Window the ADSR-Envelope is defined in the section on the bottom on the right:

In the upper part hitting a key can be simulated ("loop with..." checkbox). The defined sound is played repeatedly with the central frequency defined on the right. In between 2 keystrokes there's a pause whose duration can be adjusted too. The Sustain Time can be adjusted below, on the right of it you see the total duration of the sound. With the "One Shot" checkbox checked, the set Sustain Time is used for real keystrokes, i.e. the Sustain Time doesn't depend on how long the key is pressed anymore.

The Drehbank [MIDI Controller] Emulation

The original code just worked with a Drehbank [a specific MIDI-controllerbox, see www.doepfer.de ]. Because mose people don't have a MIDI-Controllerbox with 30 controllers lying around, I implemented a simple emulation. Below you see its window:

So if you want to change one of the scalar values on the Main Window, you have to set its Controller Value in the emulation window. Note that the hardware controllers can have a value in the range [0, 127] which is mapped to the desired parameter range by the gui [see Configuration of the GUI-Parameters / MIDI ]. I'm aware that this solution is not very convenient, but Cumulus was designed to be controlled with hardware controllers which are much more fun that this damn mouse - and I don't have enough time to do major changes in the GUI....

Configuration

Configuration of the Engine

The configuration of the Engine is done in the file Engine.config which has to be in the same directory as Engine. An example:

    # Configurationfile for GSL-Engine

    SAMPLINGRATE            44100
    INTERNALSRFACTOR        1
    CHANNELS                2
    POLYPHONY               8
    BLOCKLENGTH             650             # samples
    MAXGRAINLENGTH          400             # ms
    OSSBUFFERS              16
    OSSBUFFERSIZE           512             # size of each buffer in bytes

Explanation of the different Entries:

• SAMPLINGRATE: The Samplingrate of the output (Soundcard).
• INTERNALSRFACTOR: The internal samplingrate can be higher than the one of the output. Before playing the calculated results, they are downsampled to the external one. I didn't really compare the quality - I don't expect it to be much better with a higher internal samplingrate [but the CPU-usage will certainly be... :) ]
• CHANNELS: Defines the number of output channels. For Cumulus, only a value of 2 makes sense.
• POLYPHONY: Defines the maximum number of active voices.
• BLOCKLENGTH: The results are calculated block-wise. This value defines the size of one block in Samples [32 bit]. A small value gives you a short reaction time but lots of overhead, a large value gives you a slow reaction time but less overhead.
• MAXGRAINLENGTH: The Grains can't have unlimited length. How long Grains can be depends of the speed of your CPU. In most theoretical essays the suggested legths for Grains are in the interval [1 ms, 100 ms]; however, it can be very interesting to experiment with much longer grains.
• OSSBUFFERS: The number of DMA-buffer used by OSS.
• OSSBUFFERSIZE: The size of one DMA-buffer in Bytes.

The two OSS... parameters define the delaytime of the system. OSSBUFFERS x OSSBUFFERSIZE is the total buffersize in bytes [1 sample = 2 bytes, stereo = 2 samples]. A smaller buffer means lower delay [and higher risk of an underrun], a larger buffer imposes a higher delay but less underruns. The optimal values depend on the speed of your system - experiment!

Configuration of the GUI-Parameters / MIDI

The MIDI implementation handles messages of two MIDI-devices:

• A MIDI Controllerbox [-> Control Change Messages] on MIDI channel 0 [often a 1-based numbering scheme is used in which case it's MIDI channel 1]
• A MIDI Keyboard [-> Note On / Off Messages] on MIDI channel 1 [2 resp., see above]

If you want to change the channelnumbers [or the MIDI parsing in general], see the definitions in MIDIListener.cc.

Of course you can use a Sequencer like Cubase instead. Never tried it though, tell me your results... :)

MIDI Controllerbox

Each controller on the box sends a Control Change Comand with the following format:

   Statusbyte   Databyte 0       Databyte 1
   0xB0         Controller-Nr.   Position of the Controller [0 - 127]

In the statusbyte you can see that the first MIDI channel is used. For a controller 128 different positions are possible. Because the parameters usually have a huge value range [e.g. the Central Frequency which ranges from ~20 Hertz to ~20'000 Hertz], a configurtain file is used in which for each value

• a controller is assinged
• a value range is defined
• a law for the transformation into that range is defined

Thyis gives you the power to change the layout of the used controllers in a easy way and define the value range for each parameter. For some sounds it might be necessary to e.g. adjust the Central Frequency in a very small range as exactly as possible whilst for other sounds a as-large-as-possible range is needed without a very fine granulation of the covered values.

The configuration file gui.config must be in the same directory as gui and contains for each used parameter

1. The keywoard which identifies the parameter (see following example) 2. The number of the controller 3. The minimum value of the parameter 4. The maximum value of the parameter 5. The type [law] of the trandformation Controller Position -> Parameter Value (LIN, EXP or LOG) 6. The number of digits behind the decimal dot to display in the GUI

Example:

    # add a line for each controller-defined value of the form:
    # PARAMNAME         CTRLR# MIN-VALUE MAX-VALUE  TYPE    DigitsAfterDot

    AMPLITUDE_BASE           1      0.00    1.00    EXP     3
    AMPLITUDE_RANGE         17      0.00    1.00    EXP     3
    AMPLITUDE_STRETCH       33      0.02    10.0    EXP     2

    PANING_RANGE            18      0.00    1.00    LIN     2
    PANING_STRETCH          34      0.02    10.0    EXP     2

    CENTRAL_FREQ_RANGE      19      0.0     4.0     EXP     3   # factor for
    CENTRAL_FREQ_STRETCH    35      0.02    10.0    EXP     2   # pressed note

    FREQ_WIDTH_BASE          4      0.0     2.0     EXP     3   # factor for
    FREQ_WIDTH_RANGE        20      0.0     2.0     EXP     3   # central freq
    FREQ_WIDTH_STRETCH      36      0.02    10.0    EXP     2

    DENSITY_BASE             5      0.0     2000.0  EXP     1   # [grains/sec]
    DENSITY_RANGE           21      0.0     1000.0  EXP     1   # [grains/sec]
    DENSITY_STRETCH         37      0.02    10.0    EXP     2

    GRAIN_ATTACK_BASE        6      0.00    0.50    LIN     3   # base + range < 0.5!
    GRAIN_ATTACK_RANGE      22      0.00    0.50    LIN     3
    GRAIN_ATTACK_STRETCH    38      0.02    10.0    EXP     2

    GRAIN_HARMONY_BASE       7      0       10      LIN     1
    GRAIN_HARMONY_RANGE     23      0       10      LIN     1
    GRAIN_HARMONY_STRETCH   39      0.02    10.0    EXP     2

    # LENGTH and GRAIN_PERIOD use the same controllers
    LENGTH_BASE              8      1.0     200.0   EXP     1    # [ms]
    LENGTH_RANGE            24      0.0     50.0    LIN     1    # [ms]
    LENGTH_STRETCH          40      0.02    10.0    EXP     2

    GRAIN_PERIOD_MULT_BASE   8      1.00    32.0    LIN     1
    GRAIN_PERIOD_MULT_RANGE 24      0.00    32.0    LIN     1

    MASTER_STRETCH          49      0.02    10.0    EXP     2

    ATTACK_TIME              9      1.0     200.0   LIN     1    # [ms]
    DECAY_TIME              25      1.0     300.0   LIN     1    # [ms]
    RELEASE_TIME            41      1.0     500.0   LIN     1    # [ms]
    SUSTAIN_LEVEL           57      0.0     1.0     LIN     3
    PAUSE_TIME              10      0.0     500.0   LIN     1    # [ms]
    NOTE_CENTRAL_FREQ       26      50.0    14000.0 EXP     1    # [Hz]
    SUSTAIN_TIME            42      0.0     15000.0 EXP     1    # [ms]

MIDI Keyboard

Cumulus can play several voices which allows you to play melodies. However, this doesn't make much sense because the AGS typically creates inharmonic sounds which sound shitty in melodies. I implemented that because I needed something impressive to demonstrate which doesn't imply a lot of programming.... :)