REFERENCE


General


Symbols and numbers in a parameter file have to be limited with space, tab or return.
The values of a modul (generator, mask etc.) can be distributed over several lines.
Several moduls can also be written together in one single line.

Symbols (f, rnd, mask, accum ...) can be written in upper case or lower case letters.


Prescribed text

   { <text> }

The text in braces {} may contain function table statements, note lists and other score statements inclusive comments, which should be copied unchanged into the score file . This prescribed text must be written before any field desriptions.

Example:

{
f1 0 8193 10 1
f2 0 1024 8 0 512 1 512 0
; tables with sine wave and envelope
}


Comment

   ; <text>

Comments can be written elsewhere into the parameter file .
They begin with a semicolon ; and extend to the end of the line.


Segment function (bpf)

   ( <t1 v1> <t2 v2> <t3 v3> <..> [ipl <<val> | cos | off>] )
 
   [ <vstart> <vend> [ipl <<val> | cos | off>] ]

Almost every module in CMask can controlled by a constant or by time dependend values. The description of variable values is done by segment functions (also known as break-point functions or polygonals). Such a function have to be written within parenthesis as a sequence of time-value pairs or points (<tn vn>). The function value of the first point is also valid before its time. The same principle applies to the last point.
There is a simplified way to write functions that consists of only one segment lasting from start to end of the field. A simple segment function have brackets [] and only two numbers - the start and the end value.

Values between the given points will be calculated by linear, power or cosine function interpolation. The optional interpolation exponent follows the keyword ipl. The default for interpolation is 0, that is linear. If ipl is followed by off, the result a step function instead of interpolation.

Interpolation exponents:

exponent

result


0

linear (similar to linseg in Csound)

>0

slowly rising, fast decaying (convex, similar to expseg in Csound)

<0

fast rising. slowly decaying (concave)

cos

half-cosine interpolation (smooth curve)

off

no interpolation (steps, similar to GEN17 in Csound)

Examples:

(0 3 5 0 8 -1)   ;3 points {0,3},{5,0} and {8,-1} with linear interp.
(0 3 5 0 ipl -1) ;2 points {0,3},{5,0} with concave interp.
[10 50 ipl 2.3]  ;2 points {start,10},{end,50} with strong convex int.
[10 50 ipl cos]  ;2 points {start,10},{end,50} with smooth interpolation


Field

   f <start time> <end time>
     <parameter1>
     <parameter2>
      ...

A parameter file consists of one or any number of fields. Fields are comparable to clouds or streams in granular synthesis systems.
A field describes at least the first 3 parameter of any Csound instrument: the instrument number, the onset time (or beat) and the duration. Depending on the structure of the instrument there can be other parameters.

Every field must have a header that is marked by the letter f.
Then follow the start and the end time of the field in seconds.
After the header begins the block with parameter descriptions for p1, p2, p3 etc.
The field description ends after the last given parameter px or with a declaration of a next field.

Fields don't have to be declared in chronological order.


Parameter

   pn  <generator>
       [<mask>]
      [<quantizer>]
      [<accumulator>]
      [prec <val>]

Each CMask parameter pn will be described with one or more moduls from the processing scheme (see above).
n corresponds to the numbering in Csound score files p1, p2, p3 etc.

A CMask parameter have to contain at least one of the generators (const, item, seg, range, rnd, osc).

Any subsequent modifying moduls (mask, quant, accum) are optional. In dependence on the choosen generator there only certain modifying moduls allowed.


Precision

   prec <val>

The numbers computed by the last modul of every parameter will be rounded normally to a precision of 5, that is 5 decimal places after the point. This precision in changeable with the optional prec - value (0...5).
<val> defines the desired number of decimal places for the output, 0 results in integers, negative values are not allowed.


Generators

A generator produces numbers, which may be further processed by a mask, a quantizer or an accumulator.Currently there are the follwing generators implemented: const, seg, range, rnd, osc and item.


Constant

   const <val>

const generates a constant value val.
Possible processing with accum.

Example:

p1 const 2   ;constant instrument number


List

   item <mode> <list>

item reads one number at a time from list dependend on the mode.
Possible processing with accum.

access

mode

example


cyclic (forward loop)

cycle

(1 2 3 4) -> 1 2 3 4 1 2 3 4 1 2 3 4

swinging (for-backward loop)

swing

(1 2 3 4) -> 1 2 3 4 3 2 1 2 3 4 3 2

permutations

heap

(1 2 3 4) -> 3 2 1 4 3 1 4 2 2 3 4 1

random

random

(1 2 3 4) -> 4 2 3 3 2 1 3 4 1 2 1 4

Example:

p4 item heap (400 410 30.3 5000 1222) ;5 different values


Segment function

   seg <bpf>

seg reads function values from the segment function given in bpf.
Possible processing with quant and accum.

Example:

p3 seg (0 1 4 .3 6 1)


Random number generator

   range <val1> <val2>

range generates uniform distributed random numbers in the range {val1,val2}.
Possible processing with quant and accum.

Example:

p2 range .1 .5 ;rhythms between 0.1 and 0.5 seconds


Probability distribution generator

   rnd <func> [<val1 | bpf1> [<val2 | bpf2>]]

rnd produces random numbers according to a probability distribution func. Some of the distributions have optional parameters to describe their shape precisely. The values of these optional parameters may be constant (val) or time variant (bpf).
Possible processing with mask, quant and accum.

Probability distributions:

distribution

name

optional parameters

default

remarks


uniform

uni

-

linear

lin

<val>

1.0

; >0 : decrease
; <0 : increase

linear, increasing

rlin

-

triangle

tri

-

exponential, decreas.

exp

<val | bpf>

1.0

; only values >0

exponential, increas.

rexp

<val | bpf>

1.0

; only values >0

exponent., bilateral

bexp

<val | bpf>

1.0

; only values >0

gaussian

gauss

<val | bpf> <val | bpf>

0.1 0.5

; standard deviation
; and mean {0...1}

cauchy

cauchy

<val | bpf> <val | bpf>

0.1 0.5

; spread and mean {0...1}

beta

beta

<val | bpf> <val | bpf>

0.1 0.1

; a and b {0...1}

weibull

wei

<val | bpf> <val | bpf>

0.5 2.0

; s {0...1} and t {>0}

Example:

p4 rnd gauss (0 .1 10 .6) .5


Oscillator

    osc <func> [<freq | bpf> [<phs> [<exp>]]]

osc generates numbers according to a periodic function func in dependence on a constant or variable frequency freq and an optional phase phs.
Possible processing with mask, quant and accum.

Periodic functions:

function

name

optional parameters

default

remarks


sine

sin

<val | bpf> [<val>]

1 0

;frequenz in cps, phase {0...1}

cosine

cos

<val | bpf> [<val>]

1 0

square

square

<val | bpf> [<val>]

1 0

triangle

triangle

<val | bpf> [<val>]

1 0

saw, increasing

sawup

<val | bpf> [<val>]

1 0

saw, decreasing

sawdown

<val | bpf> [<val>]

1 0

power function,
increasing

powup

<val | bpf> [<val>] [<val>]

1 0 0

;frequenz, phase, exponent

power function,
increasing

powdown

<val | bpf> [<val>] [<val>]

1 0 0

;frequenz, phase, exponent

Example:

p4 osc sin (0 2 3 .5 ipl 1) ;from 2 to 0.5 Hz falling frequency


Modifiers

A modifier processes the numbers which was generated by a preceeding generator or another modifier.
All modifying moduls are optional, but there is only one possible order (see the processing scheme above).
The implemented modifiers are: mask, quant and accum.


Tendency mask

   mask <low | bpf> <high | bpf> [map <exp>]

The values generated by rnd or osc can can be mapped onto a time dependend range - the tendendency mask.
Both low and high boundaries may be constant or time variant (bpf).

The mapping process itself depends on the optional map-exponent: Values which was produced by rnd or osc are always in the range {0...1}. Within a mask they will now transformed by a (nonlinear) function:

y = x ^(2^exponent).

The default exponent is 0, this results in a linear transformation.
Positive exponents result in a power function. For example: an exponent 1 makes the squares of the input numbers, 0.5 will be 0.25, 0.3 will be 0.09, that is, all values gets smaller (except 0 and 1).
Negative exponents result in a root function. For example: an exponent -1 makes the square root of the input numbers, 0.5 will be 0.707, 0.3 will be 0.547, that is, all values gets larger (except 0 and 1).

Example:

p4 rnd uni
mask 50 (2 100 10 200)   ;lower limit 50, upper limit from 100 to 200


Quantizer

   quant  <q | bpf> [<s | bpf> [<o | bpf>]]

A quantizer attracts the results of the preceeding modul onto a quantization grid q. The optional strength s {0...1} (default 1) specifies to which extent the grid takes effect (1 is total quantization, 0 is no quantization at all). The optional offset o (default 0) shifts the whole grid by the given amount. Each of the 3 parameters may be constant or time variant (bpf).

Example:

p4 range 100 200
quant 20 [0 1]   ; dynam. quantization to a grid -> 100,120,140,160,180,200


Accumulator

   accum <mode> [<low | bpf> <high | bpf>] [init <exp>]

The accumulator continuously sums all its input values to an inital value init. The inital value is optional and has a default value of 0. In order to restrict the sum to a certain range it is possible to define lower and upper limits similar to tendency masks.

The accumulators behavior near by the limits can be determined by one of three limiting modes:

method

mode

parameter


without any limiting

on

with limiting

limit

<low | bpf> <high | bpf>

with limiting and reflection

mirror

<low | bpf> <high | bpf>

with cyclic closed limits

wrap

<low | bpf> <high | bpf>

Example:

p4 range -10 10
akkum mirror 100 300 init 200 


Back to Contents