Wiki

Clone wiki

cosyne / SynthLanguage

Synth Description Language

Instruments are described using a simple text-based description language.

Syntactic conventions

Basic elements

  • <number>: A signed floating-point value in decimal notation. Scientific notation is not currently supported.
  • <symbol>: An alphanumeric word, consisting of letters, digits and the underscore character and not starting with a digit.
  • <expr>: An arithmetic modulation expression comprised of variables, numbers and arithmetic operators, enclosed in curly braces {...}. As a convenience, numbers without enclosing curlies are automatically converted to expressions if needed and can thus be used wherever an expression is expected.

Sections

Cosyne instrument files are organized hierarchically into sections. A section is a tag in the form of a symbol, followed by a pair of parentheses enclosing the contents of the section. A section may contain numbers, symbols, expressions, or more sections.

Comments

Instrument files may contain C++-style comments; that is, everything from // to the end of the line is treated as a comment, and everything between /* and */ is treated as a comment.

Oscillators

Every patch can make use of up two oscillators. An oscillator section is tagged with osc1 or osc2 to identify the oscillator being defined. The following parameters are allowed within an oscillator section:

  • type(<symbol>) - The type of the oscillator. Valid options are sine, saw, rectangle, triangle, whitenoise, pinknoise, and brownnoise. Default: sine.
  • tune(<number>) - The tuning of the oscillator relative to the note the voice is playing, in semitones. Fractional values are allowed. Default: 0.
  • shape(<expr>) - For the rectangle or triangle oscillator, the shape parameter of the waveform, ranging from 0 to 1. A value of 0.5 means a square wave or symmetric triangular wave, respectively. Default: 0.5.
  • freqmod(<expr>) - This can be used to perform low frequency modulation of the oscillator frequency on top of its tuning, e.g. for vibrato. The value is a multiplier used to modulate the oscillation frequency. For frequency modulation near or at audio rates, use the fm parameter described below. Default: 1.

Mixing

The following options are available for specifying how the oscillators should be mixed together.

  • mix(<expr>) - A crossfade parameter ranging from -1 to 1 specifying how loud the two oscillators should be relative to each other. At -1, only the first oscillator is heard; at 1, only the second oscillator is heard. At 0, both oscillators are equally loud. Default: -1.
  • gain(<number>) - A master gain factor which is applied after the filter and all effects. Default: 1.
  • fm(<expr>) - Frequency modulation. If this is nonzero, the frequency of oscillator 1 is modulated by the output of oscillator 2. Higher values yield stronger modulation. At the moment, only the sine oscillator can be used as the carrier (oscillator 1) for frequency modulation. Default: 0.
  • ringmod(<expr>) - Ring modulation between 0 and 1. If this is nonzero, the output of oscillator 2 is ring modulated (multiplied) by the output of oscillator 1. Higher values yield stronger modulation. Default: 0.

Filter

One filter may be used per instrument. By default, it is disabled. It can be enabled by specifying a filter section with the following parameters:

  • type(<symbol>) - The type of the filter. Currently implemented are linear low-pass, high-pass and band-pass filters with 12dB per octave falloff (lp12, hp12, and bp12), as well as a simulation of the Moog ladder filter (mooglp).
  • cutoff(<expr>) - The cutoff frequency of the filter, in Hz. Often you will want to use the predefined variable f in this expression, which gives the frequency of the currently playing note. Default: {f}.
  • resonance(<expr>) - The resonance or Q parameter of the filter, typically ranging from 0 to 1. Default: 0.

Envelopes

ADSR envelopes are defined by sections which contain four numbers, corresponding to the attack, decay, sustain, and release parameters of the envelope. Attack is the time in seconds it takes the envelope to rise from its initial value 0 to its peak value 1 once a note-on event is received. Decay is the time in seconds to fall off from the peak level to the sustain level. Sustain is a value between 0 and 1 which gives the level during the sustain phase. The sustain phase lasts until a note-off event is received. Release is the time in seconds to fall off from the sustain level to 0.

Every instrument has a master amplitude envelope specified by the tag envelope. Further custom envelopes can be defined by the user as env1, env2, and so on; these may then be used in modulation expressions.

If the amplitude envelope is not specified, it defaults to envelope(0.1 0.1 0.5 0.3).

LFOs

Low Frequency Oscillators (LFOs) are oscillators which have a frequency below audio rate and can be used in modulation expressions. An instrument can use any number of LFOs defined by sections lfo1, lfo2, and so on. The following parameters are available in an LFO section:

  • type(<symbol>) - The type of the LFO. Valid options are sine, saw, rectangle, triangle, and sampleandhold. The option sampleandhold describes an oscillator which chooses a value between -1 and 1 at random and holds it until the next period, when a new random value is chosen. Default: sine.
  • rate(<number>) - The rate of the LFO in Hz. Default: 2.

User parameters

User parameters can be used in modulation expression just like LFOs and custom envelopes, but they are only changed whenever a ParamChange event is received from the host program. The user may define an arbitrary number of parameters, called param1, param2, and so on. A user parameter section contains just a single number defining the initial value of the parameter. E.g., the definition param1(0) tells Cosyne that this instrument has the user parameter param1 which initially is zero.

Effects

An instrument may optionally have an effects sections, which may contain an arbitrary number of effects. Effects are processed in the given order after all voices of the instrument have been mixed together, just before the final gain adjustment is made. Every effect is itself defined by a subsection of the effects section, tagged with the name of the effect and containing its parameters. Currently, effect parameters can not make use of modulation expressions. The following effects are available:

Delay

Tag: delay. An echo-like effect, with a mild lowpass filter in the feedback path. With short delay times, it can be used to cheaply emulate a reverb effect. Parameters:

  • time(<number>) - The length of the delay in seconds. Default: 0.25.
  • amount(<number>) - The amount of the delayed signal to mix into the input signal. At 0, only the input signal is heard, while at 1, the delayed signal and the input signal are equally load. Default: 0.5.
  • feedback(<number>) - The amount of the delayed signal to feed back into the delay loop. The value 0 yields a single echo (slapback delay), while 1 yields an echo that doesn't decay at all (except for the lowpass filter). Default: 0.5.

Chorus

Tag: chorus. A modulation effect which overlays several slightly detuned versions of the input signal. Is often used in order to 'fatten up' the sound of an instrument. Parameters:

  • voices(<number>) - The number of detuned voices to create. Default: 1.
  • time(<number>) - The minimum time, in seconds, by which to delay each of the voices. Default: 0.025.
  • depth(<number>) - The time, in seconds, by which the delay of each voice is modulated. Default: 0.005.
  • rate(<number>) - The rate, in Hz, at which to modulate the delay times of the voices. This is the frequency at which a voice modulates from a delay of time seconds to time+depth seconds and back. Default: 3.
  • amount(<number>) - The amount of the detuned voices to mix into the input signal. Default: 0.5.

Decimator

Tag: decimator. A lo-fi effect which reduces the input signal's sample rate by a given factor. It does this by sampling the input signal and then outputting the obtained value for a number of samples, ignoring the input signal. When a given number of samples has passed, a new sample value is obtained from the input. Parameters:

  • factor(<number>) - The number of samples for which to hold each value. The sampling rate of the input is effectively divided by this value. Default: 3.

Waveshaper

Tag: waveshaper. A distortion effect which applies a transformation function to every sample value. Parameters:

  • type(<symbol>) - The transformation function to use, determining the character of the distortion. Options are tanh, atan, and rational. Default: tanh.
  • pregain(<number>) - The amount of gain to apply before the distortion. Can be used to drive the waveshaper to higher distortion levels. Default: 2.
  • postgain(<number>) - The amount of gain to apply after the distortion. Especially with high levels of distortion, it is recommended to scale down the output in order not to obtain an excessively loud signal. Default: 0.5.
  • hardness(<number>) - Only used for the rational waveshaper, where it transitions from a soft knee to an almost linear transformation with hard clipping at extreme values. Should be between 0 and 1. Default: 0.75.

Updated