
===========================================================================
!=                                                                       *!=*

  Description

Determines if one value is not equal to another.

  Syntax

(a != b ? v1 : v2)

where a, b, v1 and v2 may be expressions, but a, b not audio-rate.

  Performance

In the above conditional, a and b are first compared. If the indicated
relation is true (a not equal to b), then the conditional expression has
the value of v1; if the relation is false, the expression has the value
of v2.

NB.: If v1 or v2 are expressions, these will be evaluated before the
conditional is determined.

In terms of binding strength, all conditional operators (i.e. the
relational operators (<, etc.), and ?, and : ) are weaker than the
arithmetic and logical operators (+, -, *, /, && and ||).

These are operators not opcodes. Therefore, they can be used within
orchestra statements, but do not form complete statements themselves.


===========================================================================
#define                                                             *#define*

  Description

Macros are textual replacements which are made in the orchestra as it is
being read. The macro system in Csound is a very simple one, and uses
the characters # and $ to define and call macros. This can save typing,
and can lead to a coherent structure and consistent style. This is
similar to, but independent of, the macro system in the score language.

#define NAME -- defines a simple macro. The name of the macro must begin
with a letter and can consist of any combination of letters and numbers.
Case is significant. This form is limiting, in that the variable names
are fixed. More flexibility can be obtained by using a macro with
arguments, described below.

#define NAME(a' b' c') -- defines a macro with arguments. This can be
used in more complex situations. The name of the macro must begin with a
letter and can consist of any combination of letters and numbers. Within
the replacement text, the arguments can be substituted by the form: $A.
In fact, the implementation defines the arguments as simple macros.
There may be up to 5 arguments, and the names may be any choice of
letters. Remember that case is significant in macro names.

  Syntax

#define NAME # replacement text #

#define NAME(a' b' c') # replacement text #

  Initialization

# replacement text # -- The replacement text is any character string
(not containing a #) and can extend over mutliple lines. The replacement
text is enclosed within the # characters, which ensure that additional
characters are not inadvertently captured.

  Performance

Some care is needed with textual replacement macros, as they can
sometimes do strange things. They take no notice of any meaning, so
spaces are significant. This is why, unlike the C programming language,
the definition has the replacement text surrounded by # characters. Used
carefully, this simple macro system is a powerful concept, but it can be
abused.


===========================================================================
#include                                                           *#include*

  Description

Includes an external file for processing.

  Syntax

#include “filename”

  Performance

It is sometimes convenient to have the orchestra arranged in a number of
files, for example with each instrument in a separate file. This style
is supported by the #include facility which is part of the macro system.
A line containing the text

#include "filename"

where the character " can be replaced by any suitable character. For
most uses the double quote symbol will probably be the most convenient.
The file name can include a full path.

This takes input from the named file until it ends, when input reverts
to the previous input. Note: Csound versions prior to 4.19 had a limit
of 20 on the depth of included files and macros.

Another suggested use of #include would be to define a set of macros
which are part of the composer's style.

An extreme form would be to have each instrument defines as a macro,
with the instrument number as a parameter. Then an entire orchestra
could be constructed from a number of #include statements followed by
macro calls.

#include "clarinet"
#include "flute"
#include "bassoon"
$CLARINET(1)
$FLUTE(2)
$BASSOON(3)

It must be stressed that these changes are at the textual level and so
take no cognizance of any meaning.

If the version of Csound is built with the CURL library the filename in
an #include statement can be an URL, recognised by including the
substring "://" in the name. This will include text via protocols such
as http, https, and ftp.


===========================================================================
#undef                                                               *#undef*

  Description

Macros are textual replacements which are made in the orchestra as it is
being read. The macro system in Csound is a very simple one, and uses
the characters # and $ to define and call macros. This can save typing,
and can lead to a coherent structure and consistent style. This is
similar to, but independent of, the macro system in the score language.

#undef NAME -- undefines a macro name. If a macro is no longer required,
it can be undefined with #undef NAME.

  Syntax

#undef NAME

  Performance

Some care is needed with textual replacement macros, as they can
sometimes do strange things. They take no notice of any meaning, so
spaces are significant. This is why, unlike the C programming language,
the definition has the replacement text surrounded by # characters. Used
carefully, this simple macro system is a powerful concept, but it can be
abused.


===========================================================================
#ifdef                                                               *#ifdef*

  Description

If a macro is defined then #ifdef can incorporate text into an orchestra
upto the next #end. This is similar to, but independent of, the macro
system in the score language.

  Syntax

#ifdef NAME

....

#else 

....

#end 

  Performance

Note that the #ifdef can be nested, like in the C preprocessor language.


===========================================================================
#ifndef                                                             *#ifndef*

  Description

If the specified macro is not defined then #ifndef can incorporate text
into an orchestra upto the next #end. This is similar to, but
independent of, the macro system in the score language.

  Syntax

#ifndef NAME

....

#else 

....

#end 

  Performance

Note that the #ifndef can be nested, like in the C preprocessor language.


===========================================================================
$NAME                                                                 *$NAME*

  Description

Macros are textual replacements which are made in the orchestra as it is
being read. The macro system in Csound is a very simple one, and uses
the characters # and $ to define and call macros. This can save typing,
and can lead to a coherent structure and consistent style. This is
similar to, but independent of, the macro system in the score language.

$NAME -- calls a defined macro. To use a macro, the name is used
following a $ character. The name is terminated by the first character
which is neither a letter nor a number. If it is necessary for the name
not to terminate with a space, a period, which will be ignored, can be
used to terminate the name. The string, $NAME., is replaced by the
replacement text from the definition. The replacement text can also
include macro calls.

  Syntax

$NAME 

  Initialization

# replacement text # -- The replacement text is any character string
(not containing a #) and can extend over mutliple lines. The replacement
text is enclosed within the # characters, which ensure that additional
characters are not inadvertently captured.

  Performance

Some care is needed with textual replacement macros, as they can
sometimes do strange things. They take no notice of any meaning, so
spaces are significant. This is why, unlike the C programming language,
the definition has the replacement text surrounded by # characters. Used
carefully, this simple macro system is a powerful concept, but it can be
abused.


===========================================================================
%                                                                         *%*

  Description

Arithmetic operators perform operations of change-sign (negate),
don't-change-sign, logical AND logical OR, add, subtract, multiply and
divide. Note that a value or an expression may fall between two of these
operators, either of which could take it as its left or right argument,
as in

a + b * c.

In such cases three rules apply:

1. * and / bind to their neighbors more strongly than + and −. Thus the
above expression is taken as

a + (b * c)

with * taking b and c and then + taking a and b * c.

2. + and − bind more strongly than &&, which in turn is stronger than ||:

a && b - c || d

is taken as

(a && (b - c)) || d

3. When both operators bind equally strongly, the operations are done
left to right:

a - b - c

is taken as

(a - b) - c

Parentheses may be used as above to force particular groupings.

The operator % returns the value of a reduced by b, so that the result,
in absolute value, is less than the absolute value of b, by repeated
subtraction. This is the same as modulus function in integers. New in
Csound version 3.50.

  Syntax

a % b  (no rate restriction)

where the arguments a and b may be further expressions.


===========================================================================
&&                                                                       *&&*

  Description

Arithmetic operators perform operations of change-sign (negate),
don't-change-sign, logical AND logical OR, add, subtract, multiply and
divide. Note that a value or an expression may fall between two of these
operators, either of which could take it as its left or right argument,
as in

a + b * c.

In such cases three rules apply:

1. * and / bind to their neighbors more strongly than + and −. Thus the
above expression is taken as

a + (b * c)

with * taking b and c and then + taking a and b * c.

2. + and − bind more strongly than &&, which in turn is stronger than ||:

a && b - c || d

is taken as

(a && (b - c)) || d

3. When both operators bind equally strongly, the operations are done
left to right:

a - b - c

is taken as

(a - b) - c

Parentheses may be used as above to force particular groupings.

  Syntax

a && b  (logical AND; not audio-rate)

where the arguments a and b may be further expressions.


===========================================================================
>                                                                         *>*

  Description

Determines if one value is greater than another.

  Syntax

(a >  b ? v1 : v2)

where a, b, v1 and v2 may be expressions, but a, b not audio-rate.

  Performance

In the above conditional, a and b are first compared. If the indicated
relation is true (a greater than b), then the conditional expression has
the value of v1; if the relation is false, the expression has the value
of v2.

NB.: If v1 or v2 are expressions, these will be evaluated before the
conditional is determined.

In terms of binding strength, all conditional operators (i.e. the
relational operators (<, etc.), and ?, and : ) are weaker than the
arithmetic and logical operators (+, -, *, /, && and ||).

These are operators not opcodes. Therefore, they can be used within
orchestra statements, but do not form complete statements themselves.


===========================================================================
>=                                                                       *>=*

  Description

Determines if one value is greater than or equal to another.

  Syntax

(a >= b ? v1 : v2)

where a, b, v1 and v2 may be expressions, but a, b not audio-rate.

  Performance

In the above conditional, a and b are first compared. If the indicated
relation is true (a greater than or equal to b), then the conditional
expression has the value of v1; if the relation is false, the expression
has the value of v2.

NB.: If v1 or v2 are expressions, these will be evaluated before the
conditional is determined.

In terms of binding strength, all conditional operators (i.e. the
relational operators (<, etc.), and ?, and : ) are weaker than the
arithmetic and logical operators (+, -, *, /, && and ||).

These are operators not opcodes. Therefore, they can be used within
orchestra statements, but do not form complete statements themselves.


===========================================================================
<                                                                         *<*

  Description

Determines if one value is less than another.

  Syntax

(a <  b ? v1 : v2)

where a, b, v1 and v2 may be expressions, but a, b not audio-rate.

  Performance

In the above conditional, a and b are first compared. If the indicated
relation is true (a less than b), then the conditional expression has
the value of v1; if the relation is false, the expression has the value
of v2.

NB.: If v1 or v2 are expressions, these will be evaluated before the
conditional is determined.

In terms of binding strength, all conditional operators (i.e. the
relational operators (<, etc.), and ?, and : ) are weaker than the
arithmetic and logical operators (+, -, *, /, && and ||).

These are operators not opcodes. Therefore, they can be used within
orchestra statements, but do not form complete statements themselves.


===========================================================================
<=                                                                       *<=*

  Description

Determines if one value is less than or equal to another.

  Syntax

(a <= b ? v1 : v2)

where a, b, v1 and v2 may be expressions, but a, b not audio-rate.

  Performance

In the above conditional, a and b are first compared. If the indicated
relation is true (a less than or equal to b), then the conditional
expression has the value of v1; if the relation is false, the expression
has the value of v2.

NB.: If v1 or v2 are expressions, these will be evaluated before the
conditional is determined.

In terms of binding strength, all conditional operators (i.e. the
relational operators (<, etc.), and ?, and : ) are weaker than the
arithmetic and logical operators (+, -, *, /, && and ||).

These are operators not opcodes. Therefore, they can be used within
orchestra statements, but do not form complete statements themselves.


===========================================================================
*                                                                         ***

  Description

Arithmetic operators perform operations of change-sign (negate),
don't-change-sign, logical AND logical OR, add, subtract, multiply and
divide. Note that a value or an expression may fall between two of these
operators, either of which could take it as its left or right argument,
as in

a + b * c.

In such cases three rules apply:

1. * and / bind to their neighbors more strongly than + and −. Thus the
above expression is taken as

a + (b * c)

with * taking b and c and then + taking a and b * c.

2. + and − bind more strongly than &&, which in turn is stronger than ||:

a && b - c || d

is taken as

(a && (b - c)) || d

3. When both operators bind equally strongly, the operations are done
left to right:

a - b - c

is taken as

(a - b) - c

Parentheses may be used as above to force particular groupings.

  Syntax

a *  b  (no rate restriction)

where the arguments a and b may be further expressions.


===========================================================================
+                                                                         *+*

  Description

Arithmetic operators perform operations of change-sign (negate),
do-no-change-sign, logical AND logical OR, add, subtract, multiply and
divide. Note that a value or an expression may fall between two of these
operators, either of which could take it as its left or right argument,
as in

a + b * c.

In such cases three rules apply:

1. * and / bind to their neighbors more strongly than + and −. Thus the
above expression is taken as

a + (b * c)

with * taking b and c and then + taking a and b * c.

2. + and − bind more strongly than &&, which in turn is stronger than ||:

a && b - c || d

is taken as

(a && (b - c)) || d

3. When both operators bind equally strongly, the operations are done
left to right:

a - b - c

is taken as

(a - b) - c

Parentheses may be used as above to force particular groupings.

  Syntax

+a  (no rate restriction)

a + b  (no rate restriction)

where the arguments a and b may be further expressions.


===========================================================================
-                                                                         *-*

  Description

Arithmetic operators perform operations of change-sign (negate),
don't-change-sign, logical AND logical OR, add, subtract, multiply and
divide. Note that a value or an expression may fall between two of these
operators, either of which could take it as its left or right argument,
as in

a + b * c.

In such cases three rules apply:

1. * and / bind to their neighbors more strongly than + and −. Thus the
above expression is taken as

a + (b * c)

with * taking b and c and then + taking a and b * c.

2. + and − bind more strongly than &&, which in turn is stronger than ||:

a && b - c || d

is taken as

(a && (b - c)) || d

3. When both operators bind equally strongly, the operations are done
left to right:

a - b - c

is taken as

(a - b) - c

Parentheses may be used as above to force particular groupings.

  Syntax

−a  (no rate restriction)

a − b  (no rate restriction)

where the arguments a and b may be further expressions.


===========================================================================
/                                                                         */*

  Description

Arithmetic operators perform operations of change-sign (negate),
don't-change-sign, logical AND logical OR, add, subtract, multiply and
divide. Note that a value or an expression may fall between two of these
operators, either of which could take it as its left or right argument,
as in

a + b * c.

In such cases three rules apply:

1. * and / bind to their neighbors more strongly than + and −. Thus the
above expression is taken as

a + (b * c)

with * taking b and c and then + taking a and b * c.

2. + and − bind more strongly than &&, which in turn is stronger than ||:

a && b - c || d

is taken as

(a && (b - c)) || d

3. When both operators bind equally strongly, the operations are done
left to right:

a - b - c

is taken as

(a - b) - c

Parentheses may be used as above to force particular groupings.

  Syntax

a /  b  (no rate restriction)

where the arguments a and b may be further expressions.


===========================================================================
=                                                                         *=*

  Syntax

ares = xarg

ires = iarg

kres = karg

ires, ... = iarg, ...

kres, ... = karg, ...

table [ kval] = karg

  Description

Performs a simple assignment.

  Initialization

= (simple assignment) - Put the value of the expression iarg (karg,
xarg) into the named result. This provides a means of saving an
evaluated result for later use.

From version 5.13 onwards the i- and k-rate versions of assignment can
take a number of outputs, and an equal or less number of inputs. If
there are less the last value is repeated as necessary.

From version 5.14 values can be assigned to elements of a vector with
the square bracket form.


===========================================================================
+=                                                                       *+=*

  Syntax

ares += xarg

ires += iarg

kres += karg

table [ kval] += karg

  Description

Performs an add and assign.

  Initialization

+= - Adds the value of the expression iarg (karg, xarg) into the named
result. This provides a means of saving an evaluated result for later use.


===========================================================================
==                                                                       *==*

  Description

Compares two values for equality.

  Syntax

(a == b ? v1 : v2)

where a, b, v1 and v2 may be expressions, but a, b not audio-rate.

  Performance

In the above conditional, a and b are first compared. If the indicated
relation is true (a is equal to b), then the conditional expression has
the value of v1; if the relation is false, the expression has the value
of v2. (For convenience, a sole "=" will function as "= =".)

NB.: If v1 or v2 are expressions, these will be evaluated before the
conditional is determined.

In terms of binding strength, all conditional operators (i.e. the
relational operators (<, etc.), and ?, and : ) are weaker than the
arithmetic and logical operators (+, -, *, /, && and ||).

These are operators not opcodes. Therefore, they can be used within
orchestra statements, but do not form complete statements themselves.


===========================================================================
^                                                                         *^*

  Description

Arithmetic operators perform operations of change-sign (negate),
don't-change-sign, logical AND logical OR, add, subtract, multiply and
divide. Note that a value or an expression may fall between two of these
operators, either of which could take it as its left or right argument,
as in

a + b * c.

In such cases three rules apply:

1. * and / bind to their neighbors more strongly than + and −. Thus the
above expression is taken as

a + (b * c)

with * taking b and c and then + taking a and b * c.

2. + and − bind more strongly than &&, which in turn is stronger than ||:

a && b - c || d

is taken as

(a && (b - c)) || d

3. When both operators bind equally strongly, the operations are done
left to right:

a - b - c

is taken as

(a - b) - c

Parentheses may be used as above to force particular groupings.

The operator ^ raises a to the b power. b may not be audio-rate. Use
with caution as precedence may not work correctly. See pow. (New in
Csound version 3.493.)

  Syntax

a ^  b  (b not audio-rate)

where the arguments a and b may be further expressions.


===========================================================================
||                                                                       *||*

  Description

Arithmetic operators perform operations of change-sign (negate),
don't-change-sign, logical AND logical OR, add, subtract, multiply and
divide. Note that a value or an expression may fall between two of these
operators, either of which could take it as its left or right argument,
as in

a + b * c.

In such cases three rules apply:

1. * and / bind to their neighbors more strongly than + and −. Thus the
above expression is taken as

a + (b * c)

with * taking b and c and then + taking a and b * c.

2. + and − bind more strongly than &&, which in turn is stronger than ||:

a && b - c || d

is taken as

(a && (b - c)) || d

3. When both operators bind equally strongly, the operations are done
left to right:

a - b - c

is taken as

(a - b) - c

Parentheses may be used as above to force particular groupings.

  Syntax

a || b  (logical OR; not audio-rate)

where the arguments a and b may be further expressions.


===========================================================================
0dbfs                                                                 *0dbfs*

  Description

Sets the value of 0 decibels using full scale amplitude.

  Syntax

0dbfs = iarg

0dbfs 

  Initialization

iarg -- the value of 0 decibels using full scale amplitude.

  Performance

The default is 32767, so all existing orcs should work.

Amplitude values in Csound are always relative to a "0dbfs" value
representing the peak available amplitude before clipping. In the
original Csound, this value was always 32767, corresponding to the
bipolar range of a 16bit soundfile or 16bit AD/DA codec. This remains
the default peak amplitude for Csound, for backward compatibility. The
0dbfs value enables Csound to produce appropriately scaled values to
whatever output format is being used, whether 16bit integer, 24bit
integer, 32bit floats, or even 32bit integers.

OdBFS can be defined in the header, to set the amplitude reference
Csound will use, but it can also be used as a varible inside instruments
like this:

ipeak = 0dbfs

asig oscil 0dbfs, freq, 1
     out   asig * 0.3 * 0dbfs

The purpose of the 0dbfs opcode is for people to start to code
0dbfs-relatively (and use the ampdbfs() opcodes a lot more!), rather
than use explicit sample values. Using 0dbfs=1 is in accordance to
industry practice, as ranges from -1 to 1 are used in most commercial
plugin formats and in most other synthesis systems like Pure Data.

Floats written to a file, when 0dbfs = 1, will in effect go through no
range translation at all. So the numbers in the file are exactly what
the orc says they are.

For more details on amplitude values in Csound, see the section
Amplitude values in Csound


===========================================================================
<<                                                                       *<<*

  Description

The bitshift operators shift the bits to the left or to the right the
number of bits given.

The priority of these operators is less binding that the arithmetic
ones, but more binding that the comparisons.

Parentheses may be used as above to force particular groupings.

  Syntax

a << b  (bitshift left)

where the arguments a and b may be further expressions.


===========================================================================
>>                                                                       *>>*

  Description

The bitshift operators shift the bits to the left or to the right the
number of bits given.

The priority of these operators is less binding that the arithmetic
ones, but more binding that the comparisons.

Parentheses may be used as above to force particular groupings.

  Syntax

a >> b  (bitshift left)

where the arguments a and b may be further expressions.


===========================================================================
&                                                                         *&*

  Description

The bitwise operators perform operations of bitwise AND, bitwise OR,
bitwise NOT and bitwise non-equivalence.

  Syntax

a & b  (bitwise AND)

where the arguments a and b may be further expressions. They are
converted to the nearest integer to machine precision and then the
operation is performed.

  Performance

The priority of these operators is less binding that the arithmetic
ones, but more binding that the comparisons.

Parentheses may be used as above to force particular groupings.


===========================================================================
|                                                                         *|*

  Description

The bitwise operators perform operations of bitwise AND, bitwise OR,
bitwise NOT and bitwise non-equivalence.

  Syntax

a | b  (bitwise OR)

where the arguments a and b may be further expressions. They are
converted to the nearest integer to machine precision and then the
operation is performed.

  Performance

The priority of these operators is less binding that the arithmetic
ones, but more binding that the comparisons.

Parentheses may be used as above to force particular groupings.

For an example of usage, see the entry for &


===========================================================================
¬                                                                         *¬*

  Description

The bitwise operators perform operations of bitwise AND, bitwise OR,
bitwise NOT and bitwise non-equivalence.

The priority of these operators is less binding that the arithmetic
ones, but more binding that the comparisons.

Parentheses may be used as above to force particular groupings.

  Syntax

~ a  (bitwise NOT)

where the argument a may be a further expression. It is converted to the
nearest integer to machine precision and then the operation is performed.


===========================================================================
#                                                                         *#*

  Description

The bitwise operators perform operations of bitwise AND, bitwise OR,
bitwise NOT and bitwise non-equivalence.

The priority of these operators is less binding that the arithmetic
ones, but more binding that the comparisons.

Parentheses may be used as above to force particular groupings.

  Syntax

a # b  (bitwise NON EQUIVALENCE)

where the arguments a and b may be further expressions. They are
converted to the nearest integer to machine precision and then the
operation is performed.


===========================================================================
a                                                                         *a*

  Description

Converts a k-rate parameter to an a-rate value with interpolation.

  Syntax

a(x) (control-rate args only)

where the argument within the parentheses may be an expression. Value
converters perform arithmetic translation from units of one kind to
units of another. The result can then be a term in a further expression.


===========================================================================
abs                                                                     *abs*

  Description

Returns the absolute value of x.

  Syntax

abs(x) (no rate restriction)

where the argument within the parentheses may be an expression. Value
converters perform arithmetic translation from units of one kind to
units of another. The result can then be a term in a further expression.


===========================================================================
active                                                               *active*

  Description

Returns the number of active instances of an instrument with options to
ignore releasing instances.

  Syntax

ir active insnum [,iopt [,inorel]]

ir active Sinsname [,iopt [,inorel]]

kres active kinsnum [,iopt [,inorel]]

  Initialization

insnum -- number or string name of the instrument to be reported

Sinsname -- instrument name

iopt -- select currently active (zero, default), or all every active
(non zero)

inorel -- if non-zero ignore instruments in release phase (zero,
default), only valid if iopts is zero.

  Performance

kinsnum -- number or string name of the instrument to be reported

active returns the number of active instances of instrument number
insnum/kinsnum (or named instrument Sinsname). As of Csound 4.17 the
output is updated at k-rate (if input arg is k-rate), to allow running
count of instr instances.

As of Csound 5.17 if the instrument number is given as zero then all
instruments are counted.


===========================================================================
adsr                                                                   *adsr*

  Description

Calculates the classical ADSR envelope using linear segments.

  Syntax

ares adsr iatt, idec, islev, irel [, idel]

kres adsr iatt, idec, islev, irel [, idel]

  Initialization

iatt -- duration of attack phase

idec -- duration of decay

islev -- level for sustain phase

irel -- duration of release phase

idel -- period of zero before the envelope starts

  Performance

The envelope generated is the range 0 to 1 and may need to be scaled
further, depending on the amplitude required. If using 0dbfs = 1,
scaling down will probably be required since playing more than one note
might result in clipping. If not using 0dbfs, scaling to a large
amplitude (e.g. 32000) might be required.

The envelope may be described as:

Picture of an ADSR envelope.

Picture of an ADSR envelope.

The length of the sustain is calculated from the length of the note.
This means adsr is not suitable for use with MIDI events. The opcode
madsr uses the linsegr mechanism, and so can be used in MIDI applications.

adsr is new in Csound version 3.49.


===========================================================================
adsyn                                                                 *adsyn*

  Description

Output is an additive set of individually controlled sinusoids, using an
oscillator bank.

  Syntax

ares adsyn kamod, kfmod, ksmod, ifilcod

  Initialization

ifilcod -- integer or character-string denoting a control-file derived
from analysis of an audio signal. An integer denotes the suffix of a
file adsyn.m or pvoc.m; a character-string (in double quotes) gives a
filename, optionally a full pathname. If not fullpath, the file is
sought first in the current directory, then in the one given by the
environment variable SADIR (if defined). adsyn control contains
breakpoint amplitude- and frequency-envelope values organized for
oscillator resynthesis, while pvoc control contains similar data
organized for fft resynthesis. Memory usage depends on the size of the
files involved, which are read and held entirely in memory during
computation but are shared by multiple calls (see also lpread).

  Performance

kamod -- amplitude factor of the contributing partials.

kfmod -- frequency factor of the contributing partials. It is a
control-rate transposition factor: a value of 1 incurs no transposition,
1.5 transposes up a perfect fifth, and .5 down an octave.

ksmod -- speed factor of the contributing partials.

adsyn synthesizes complex time-varying timbres through the method of
additive synthesis. Any number of sinusoids, each individually
controlled in frequency and amplitude, can be summed by high-speed
arithmetic to produce a high-fidelity result.

Component sinusoids are described by a control file describing amplitude
and frequency tracks in millisecond breakpoint fashion. Tracks are
defined by sequences of 16-bit binary integers:

-1, time, amp, time, amp,... 
-2, time, freq, time, freq,...

such as from hetrodyne filter analysis of an audio file. (For details
see hetro.) The instantaneous amplitude and frequency values are used by
an internal fixed-point oscillator that adds each active partial into an
accumulated output signal. While there is a practical limit (limit
removed in version 3.47) on the number of contributing partials, there
is no restriction on their behavior over time. Any sound that can be
described in terms of the behavior of sinusoids can be synthesized by
adsyn alone.

Sound described by an adsyn control file can also be modified during
re-synthesis. The signals kamod, kfmod, ksmod will modify the amplitude,
frequency, and speed of contributing partials. These are multiplying
factors, with kfmod modifying the frequency and ksmod modifying the
speed with which the millisecond breakpoint line-segments are traversed.
Thus .7, 1.5, and 2 will give rise to a softer sound, a perfect fifth
higher, but only half as long. The values 1,1,1 will leave the sound
unmodified. Each of these inputs can be a control signal.


===========================================================================
adsynt                                                               *adsynt*

  Description

Performs additive synthesis with an arbitrary number of partials, not
necessarily harmonic.

  Syntax

ares adsynt kamp, kcps, iwfn, ifreqfn, iampfn, icnt [, iphs]

  Initialization

iwfn -- table containing a waveform, usually a sine. Table values are
not interpolated for performance reasons, so larger tables provide
better quality.

ifreqfn -- table containing frequency values for each partial. ifreqfn
may contain beginning frequency values for each partial, but is usually
used for generating parameters at runtime with tablew. Frequencies must
be relative to kcps. Size must be at least icnt.

iampfn -- table containing amplitude values for each partial. iampfn may
contain beginning amplitude values for each partial, but is usually used
for generating parameters at runtime with tablew. Amplitudes must be
relative to kamp. Size must be at least icnt.

icnt -- number of partials to be generated

iphs -- initial phase of each oscillator, if iphs = -1, initialization
is skipped. If iphs > 1, all phases will be initialized with a random
value.

  Performance

kamp -- amplitude of note

kcps -- base frequency of note. Partial frequencies will be relative to
kcps.

Frequency and amplitude of each partial is given in the two tables
provided. The purpose of this opcode is to have an instrument generate
synthesis parameters at k-rate and write them to global parameter tables
with the tablew opcode.


===========================================================================
adsynt2                                                             *adsynt2*

  Description

Performs additive synthesis with an arbitrary number of partials, not
necessarily harmonic. (see adsynt for detailed manual)

  Syntax

ar adsynt2 kamp, kcps, iwfn, ifreqfn, iampfn, icnt [, iphs]

  Initialization

iwfn -- table containing a waveform, usually a sine. Table values are
not interpolated for performance reasons, so larger tables provide
better quality.

ifreqfn -- table containing frequency values for each partial. ifreqfn
may contain beginning frequency values for each partial, but is usually
used for generating parameters at runtime with tablew. Frequencies must
be relative to kcps. Size must be at least icnt.

iampfn -- table containing amplitude values for each partial. iampfn may
contain beginning amplitude values for each partial, but is usually used
for generating parameters at runtime with tablew. Amplitudes must be
relative to kamp. Size must be at least icnt.

icnt -- number of partials to be generated

iphs -- initial phase of each oscillator, if iphs = -1, initialization
is skipped. If iphs > 1, all phases will be initialized with a random
value.

  Performance

kamp -- amplitude of note

kcps -- base frequency of note. Partial frequencies will be relative to
kcps.

Frequency and amplitude of each partial is given in the two tables
provided. The purpose of this opcode is to have an instrument generate
synthesis parameters at k-rate and write them to global parameter tables
with the tablew opcode.

adsynt2 is identical to adsynt (by Peter Neubäcker), except it provides
linear interpolation for amplitude envelopes of each partial. It is a
bit slower than adsynt, but interpolation higly improves sound quality
in fast amplitude envelope transients when kr < sr (i.e. when ksmps >
1). No interpolation is provided for pitch envelopes, since in this case
sound quality degradation is not so evident even with high values of
ksmps. It is not recommended when kr = sr, in this case adsynt is better
(since it is faster).


===========================================================================
aftouch                                                             *aftouch*

  Description

Get the current after-touch value for this channel.

  Syntax

kaft aftouch [imin] [, imax]

  Initialization

imin (optional, default=0) -- minimum limit on values obtained.

imax (optional, default=127) -- maximum limit on values obtained.

  Performance

Get the current after-touch value for this channel.


===========================================================================
alpass                                                               *alpass*

  Description

Reverberates an input signal with a flat frequency response.

  Syntax

ares alpass asig, xrvt, ilpt [, iskip] [, insmps]

  Initialization

ilpt -- loop time in seconds, which determines the “echo density” of the
reverberation. This in turn characterizes the “color” of the filter
whose frequency response curve will contain ilpt * sr/2 peaks spaced
evenly between 0 and sr/2 (the Nyquist frequency). Loop time can be as
large as available memory will permit. The space required for an n
second loop is 4n*sr bytes. The delay space is allocated and returned as
in delay.

iskip (optional, default=0) -- initial disposition of delay-loop data
space (cf. reson). The default value is 0.

insmps (optional, default=0) -- delay amount, as a number of samples.

  Performance

xrvt -- the reverberation time (defined as the time in seconds for a
signal to decay to 1/1000, or 60dB down from its original amplitude).

This filter reiterates the input with an echo density determined by loop
time ilpt. The attenuation rate is independent and is determined by
xrvt, the reverberation time (defined as the time in seconds for a
signal to decay to 1/1000, or 60dB down from its original amplitude).
Output will begin to appear immediately.


===========================================================================
alwayson                                                           *alwayson*

  Description

Activates the indicated instrument in the orchestra header, without need
for an i statement. Instruments must be activated in the same order as
they are defined.

The alwayson opcode is designed to simplify the definition of re-usable
orchestras with signal processing or effects chains and networks.

  Syntax

 alwayson Tinstrument [p4, ..., pn]

  Initialization

Tinstrument -- String name of the instrument definition to be turned on.

[p4, ..., pn] -- Optional pfields to be passed to the instrument, in the
same order and type as if this were an i statement.

When the instrument is activated, p1 is the insno, p2 is 0, and p3 is
-1. Pfields from p4 on may optionally be sent to the instrument.


===========================================================================
ampdb                                                                 *ampdb*

  Description

Returns the amplitude equivalent of the decibel value x. Thus:

  * 60 dB = 1000

  * 66 dB = 1995.262

  * 72 dB = 3891.07

  * 78 dB = 7943.279

  * 84 dB = 15848.926

  * 90 dB = 31622.764

  Syntax

ampdb(x)  (no rate restriction)


===========================================================================
ampdbfs                                                             *ampdbfs*

  Description

Returns the amplitude equivalent of the full scale decibel (dB FS) value
x. The logarithmic full scale decibel values will be converted to linear
16-bit signed integer values from −32,768 to +32,767.

  Syntax

ampdbfs(x)  (no rate restriction)


===========================================================================
ampmidi                                                             *ampmidi*

  Description

Get the velocity of the current MIDI event.

  Syntax

iamp ampmidi iscal [, ifn]

  Initialization

iscal -- i-time scaling factor

ifn (optional, default=0) -- function table number of a normalized
translation table, by which the incoming value is first interpreted. The
default value is 0, denoting no translation.

  Performance

Get the velocity of the current MIDI event, optionally pass it through a
normalized translation table, and return an amplitude value in the range
0 - iscal.


===========================================================================
ampmidid                                                           *ampmidid*

  Description

Musically map MIDI velocity to peak amplitude within a specified dynamic
range in decibels.

  Syntax

iamplitude ampmidid ivelocity, idecibels

kamplitude ampmidid kvelocity, idecibels

  Initialization

iamplitude -- Amplitude.

ivelocity -- MIDI velocity number, ranging from 0 through 127.

idecibels -- Desired dynamic range in decibels.

  Performance

kamplitude -- Amplitude.

kvelocity -- MIDI velocity number, ranging from 0 through 127.

Musically map MIDI velocity to peak amplitude within a specified dynamic
range in decibels: a = (m * v + b) ^ 2, where a = amplitude, v = MIDI
velocity, r = 10 ^ (R / 20), b = 127 / (126 * sqrt( r )) - 1 / 126, m =
(1 - b) / 127, and R = specified dynamic range in decibels. See Roger
Dannenberg, "The Interpretation of MIDI Velocity," in Georg Essl and
Ichiro Fujinaga (Eds.), Proceedings of the 2006 International Computer
Music Conference, November 6-11, 2006 (San Francisco: The International
Computer Music Association), pp. 193-196.


===========================================================================
areson                                                               *areson*

  Description

A notch filter whose transfer functions are the complements of the reson
opcode.

  Syntax

ares areson asig, kcf, kbw [, iscl] [, iskip]

ares areson asig, acf, kbw [, iscl] [, iskip]

ares areson asig, kcf, abw [, iscl] [, iskip]

ares areson asig, acf, abw [, iscl] [, iskip]

  Initialization

iscl (optional, default=0) -- coded scaling factor for resonators. A
value of 1 signifies a peak response factor of 1, i.e. all frequencies
other than kcf/acf are attenuated in accordance with the (normalized)
response curve. A value of 2 raises the response factor so that its
overall RMS value equals 1. (This intended equalization of input and
output power assumes all frequencies are physically present; hence it is
most applicable to white noise.) A zero value signifies no scaling of
the signal, leaving that to some later adjustment (see balance). The
default value is 0.

iskip (optional, default=0) -- initial disposition of internal data
space. Since filtering incorporates a feedback loop of previous output,
the initial status of the storage space used is significant. A zero
value will clear the space; a non-zero value will allow previous
information to remain. The default value is 0.

  Performance

ares -- the output signal at audio rate.

asig -- the input signal at audio rate.

kcf/acf -- the center frequency of the filter, or frequency position of
the peak response.

kbw/abw -- bandwidth of the filter (the Hz difference between the upper
and lower half-power points).

areson is a filter whose transfer functions is the complement of reson.
Thus areson is a notch filter whose transfer functions represents the
“filtered out” aspects of their complements. However, power scaling is
not normalized in areson but remains the true complement of the
corresponding unit. Thus an audio signal, filtered by parallel matching
reson and areson units, would under addition simply reconstruct the
original spectrum.

This property is particularly useful for controlled mixing of different
sources (see lpreson). Complex response curves such as those with
multiple peaks can be obtained by using a bank of suitable filters in
series. (The resultant response is the product of the component
responses.) In such cases, the combined attenuation may result in a
serious loss of signal power, but this can be regained by the use of
balance.

  Warning
When used with iscl this opcode is not a notch filter but similar to reson.


===========================================================================
aresonk                                                             *aresonk*

  Description

A notch filter whose transfer functions are the complements of the reson
opcode.

  Syntax

kres aresonk ksig, kcf, kbw [, iscl] [, iskip]

  Initialization

iscl (optional, default=0) -- coded scaling factor for resonators. A
value of 1 signifies a peak response factor of 1, i.e. all frequencies
other than kcf are attenuated in accordance with the (normalized)
response curve. A value of 2 raises the response factor so that its
overall RMS value equals 1. (This intended equalization of input and
output power assumes all frequencies are physically present; hence it is
most applicable to white noise.) A zero value signifies no scaling of
the signal, leaving that to some later adjustment (see balance). The
default value is 0.

iskip (optional, default=0) -- initial disposition of internal data
space. Since filtering incorporates a feedback loop of previous output,
the initial status of the storage space used is significant. A zero
value will clear the space; a non-zero value will allow previous
information to remain. The default value is 0.

  Performance

kres -- the output signal at control-rate.

ksig -- the input signal at control-rate.

kcf -- the center frequency of the filter, or frequency position of the
peak response.

kbw -- bandwidth of the filter (the Hz difference between the upper and
lower half-power points).

aresonk is a filter whose transfer functions is the complement of
resonk. Thus aresonk is a notch filter whose transfer functions
represents the “filtered out” aspects of their complements. However,
power scaling is not normalized in aresonk but remains the true
complement of the corresponding unit.


===========================================================================
atone                                                                 *atone*

  Description

A hi-pass filter whose transfer functions are the complements of the
tone opcode.

  Syntax

ares atone asig, khp [, iskip]

  Initialization

iskip (optional, default=0) -- initial disposition of internal data
space. Since filtering incorporates a feedback loop of previous output,
the initial status of the storage space used is significant. A zero
value will clear the space; a non-zero value will allow previous
information to remain. The default value is 0.

  Performance

ares -- the output signal at audio rate.

asig -- the input signal at audio rate.

khp -- the response curve's half-power point, in Hertz. Half power is
defined as peak power / root 2.

atone is a filter whose transfer functions is the complement of tone.
atone is thus a form of high-pass filter whose transfer functions
represent the “filtered out” aspects of their complements. However,
power scaling is not normalized in atone but remains the true complement
of the corresponding unit. Thus an audio signal, filtered by parallel
matching tone and atone units, would under addition simply reconstruct
the original spectrum.

This property is particularly useful for controlled mixing of different
sources (see lpreson). Complex response curves such as those with
multiple peaks can be obtained by using a bank of suitable filters in
series. (The resultant response is the product of the component
responses.) In such cases, the combined attenuation may result in a
serious loss of signal power, but this can be regained by the use of
balance.


===========================================================================
atonek                                                               *atonek*

  Description

A hi-pass filter whose transfer functions are the complements of the
tonek opcode.

  Syntax

kres atonek ksig, khp [, iskip]

  Initialization

iskip (optional, default=0) -- initial disposition of internal data
space. Since filtering incorporates a feedback loop of previous output,
the initial status of the storage space used is significant. A zero
value will clear the space; a non-zero value will allow previous
information to remain. The default value is 0.

  Performance

kres -- the output signal at control-rate.

ksig -- the input signal at control-rate.

khp -- the response curve's half-power point, in Hertz. Half power is
defined as peak power / root 2.

atonek is a filter whose transfer functions is the complement of tonek.
atonek is thus a form of high-pass filter whose transfer functions
represent the “filtered out” aspects of their complements. However,
power scaling is not normalized in atonek but remains the true
complement of the corresponding unit.


===========================================================================
atonex                                                               *atonex*

  Description

atonex is equivalent to a filter consisting of more layers of atone with
the same arguments, serially connected. Using a stack of a larger number
of filters allows a sharper cutoff. They are faster than using a larger
number instances in a Csound orchestra of the old opcodes, because only
one initialization and k- cycle are needed at time and the audio loop
falls entirely inside the cache memory of processor.

  Syntax

ares atonex asig, khp [, inumlayer] [, iskip]

ares atonex asig, ahp [, inumlayer] [, iskip]

  Initialization

inumlayer (optional) -- number of elements in the filter stack. Default
value is 4.

iskip (optional, default=0) -- initial disposition of internal data
space. Since filtering incorporates a feedback loop of previous output,
the initial status of the storage space used is significant. A zero
value will clear the space; a non-zero value will allow previous
information to remain. The default value is 0.

  Performance

asig -- input signal

khp/ahp -- the response curve's half-power point. Half power is defined
as peak power / root 2.


===========================================================================
ATSadd                                                               *ATSadd*

  Description

ATSadd reads from an ATS analysis file and uses the data to perform
additive synthesis using an internal array of interpolating oscillators.

  Syntax

ar ATSadd ktimepnt, kfmod, iatsfile, ifn, ipartials[, ipartialoffset, \
        ipartialincr, igatefn]

  Initialization

iatsfile – the ATS number (n in ats.n) or the name in quotes of the
analysis file made using ATS.

ifn – table number of a stored function containing a sine wave for
ATSadd and a cosine for ATSaddnz (see examples below for more info)

ipartials – number of partials that will be used in the resynthesis (the
noise has a maximum of 25 bands)

ipartialoffset (optional) – is the first partial used (defaults to 0).

ipartialincr (optional) – sets an increment by which these synthesis
opcodes counts up from ipartialoffset for ibins components in the
re-synthesis (defaults to 1).

igatefn (optional) – is the number of a stored function which will be
applied to the amplitudes of the analysis bins before resynthesis takes
place. If igatefn is greater than 0 the amplitudes of each bin will be
scaled by igatefn through a simple mapping process. First, the
amplitudes of all of the bins in all of the frames in the entire
analysis file are compared to determine the maximum amplitude value.
This value is then used to create normalized amplitudes as indices into
the stored function igatefn. The maximum amplitude will map to the last
point in the function. An amplitude of 0 will map to the first point in
the function. Values between 0 and 1 will map accordingly to points
along the function table. See the examples below.

  Performance

ktimepnt – The time pointer in seconds used to index the ATS file. Used
for ATSadd exactly the same as for pvoc.

ATSadd and ATSaddnz are based on pvadd by Richard Karpen and use files
created by Juan Pampin's ATS (Analysis - Transformation - Synthesis).

kfmod – A control-rate transposition factor: a value of 1 incurs no
transposition, 1.5 transposes up a perfect fifth, and .5 down an octave.
Used for ATSadd exactly the same as for pvoc.

ATSadd reads from an ATS analysis file and uses the data to perform
additive synthesis using an internal array of interpolating oscillators.
The user supplies the wave table (usually one period of a sine wave),
and can choose which analysis partials will be used in the re-synthesis.


===========================================================================
ATSaddnz                                                           *ATSaddnz*

  Description

ATSaddnz reads from an ATS analysis file and uses the data to perform
additive synthesis using a modified randi function.

  Syntax

ar ATSaddnz ktimepnt, iatsfile, ibands[, ibandoffset, ibandincr]

  Initialization

iatsfile – the ATS number (n in ats.n) or the name in quotes of the
analysis file made using ATS.

ibands – number of noise bands that will be used in the resynthesis (the
noise has a maximum of 25 bands)

ibandoffset (optional) – is the first noise band used (defaults to 0).

ibandincr (optional) – sets an increment by which these synthesis
opcodes counts up from ibandoffset for ibins components in the
re-synthesis (defaults to 1).

  Performance

ktimepnt – The time pointer in seconds used to index the ATS file. Used
for ATSaddnz exactly the same as for pvoc and ATSadd.

ATSaddnz and ATSadd are based on pvadd by Richard Karpen and use files
created by Juan Pampin's ATS (Analysis - Transformation - Synthesis).

ATSaddnz also reads from an ATS file but it resynthesizes the noise from
noise energy data contained in the ATS file. It uses a modified randi
function to create band limited noise and modulates that with a cosine
wave, to synthesize a user specified selection of frequency bands.
Modulating the noise is required to put the band limited noise in the
correct place in the frequency spectrum.


===========================================================================
ATSbufread                                                       *ATSbufread*

  Description

ATSbufread reads data from and ATS data file and stores it in an
internal data table of frequency, amplitude pairs.

  Syntax

ATSbufread ktimepnt, kfmod, iatsfile, ipartials[, ipartialoffset, \
          ipartialincr]

  Initialization

iatsfile – the ATS number (n in ats.n) or the name in quotes of the
analysis file made using ATS.

ipartials – number of partials that will be used in the resynthesis (the
noise has a maximum of 25 bands)

ipartialoffset (optional) – is the first partial used (defaults to 0).

ipartialincr (optional) – sets an increment by which these synthesis
opcodes counts up from ipartialoffset for ibins components in the
re-synthesis (defaults to 1).

  Performance

ktimepnt – The time pointer in seconds used to index the ATS file. Used
for ATSbufread exactly the same as for pvoc.

kfmod – an input for performing pitch transposition or frequency
modulation on all of the synthesized partials, if no fm or pitch change
is desired then use a 1 for this value.

ATSbufread is based on pvbufread by Richard Karpen. ATScross,
ATSinterpread and ATSpartialtap are all dependent on ATSbufread just as
pvcross and pvinterp are on pvbufread. ATSbufread reads data from and
ATS data file and stores it in an internal data table of frequency,
amplitude pairs. The data stored by an ATSbufread can only be accessed
by other unit generators, and therefore, due to the architecture of
Csound, an ATSbufread must come before (but not necessarily directly)
any dependent unit generator. Besides the fact that ATSbufread doesn't
output any data directly, it works almost exactly as ATSadd. The ugen
uses a time pointer (ktimepnt) to index the data in time, ipartials,
ipartialoffset and ipartialincr to select which partials to store in the
table and kfmod to scale partials in frequency.


===========================================================================
ATScross                                                           *ATScross*

  Description

ATScross uses data from an ATS analysis file and data from an ATSbufread
to perform cross synthesis.

  Syntax

ar ATScross ktimepnt, kfmod, iatsfile, ifn, kmylev, kbuflev, ipartials \
          [, ipartialoffset, ipartialincr]

  Initialization

iatsfile – integer or character-string denoting a control-file derived
from ATS analysis of an audio signal. An integer denotes the suffix of a
file ATS.m; a character-string (in double quotes) gives a filename,
optionally a full pathname. If not full-path, the file is sought first
in the current directory, then in the one given by the environment
variable SADIR (if defined).

ifn – table number of a stored function containing a sine wave.

ipartials – number of partials that will be used in the resynthesis

ipartialoffset (optional) – is the first partial used (defaults to 0).

ipartialincr (optional) – sets an increment by which these synthesis
opcodes counts up from ipartialoffset for ibins components in the
re-synthesis (defaults to 1).

  Performance

ktimepnt – The time pointer in seconds used to index the ATS file. Used
for ATScross exactly the same as for pvoc.

kfmod – an input for performing pitch transposition or frequency
modulation on all of the synthesized partials, if no fm or pitch change
is desired then use a 1 for this value.

kmylev - scales the ATScross component of the frequency spectrum applied
to the partials from the ATS file indicated by the ATScross opcode. The
frequency spectrum information comes from the ATScross ATS file. A value
of 1 (and 0 for kbuflev) gives the same results as ATSadd.

kbuflev - scales the ATSbufread component of the frequency spectrum
applied to the partials from the ATS file indicated by the ATScross
opcode. The frequency spectrum information comes from the ATSbufread ATS
file. A value of 1 (and 0 for kmylev) results in partials that have
frequency information from the ATS file given by the ATScross, but
amplitudes imposed by data from the ATS file given by ATSbufread.

ATScross uses data from an ATS analysis file (indicated by iatsfile) and
data from an ATSbufread to perform cross synthesis. ATScross uses
ktimepnt, kfmod, ipartials, ipartialoffset and ipartialincr just like
ATSadd. ATScross synthesizes a sine-wave for each partial selected by
the user and uses the frequency of that partial (after scaling in
frequency by kfmod) to index the table created by ATSbufread.
Interpolation is used to get in-between values. ATScross uses the sum of
the amplitude data from its ATS file (scaled by kmylev) and the
amplitude data gained from an ATSbufread (scaled by kbuflev) to scale
the amplitude of each partial it synthesizes. Setting kmylev to one and
kbuflev to zero will make ATScross act exactly like ATSadd. Setting
kmylev to zero and kbuflev to one will produce a sound that has all the
partials selected by the ATScross ugen, but with amplitudes taken from
an ATSbufread. The time pointers of the ATSbufread and ATScross do not
need to be the same.


===========================================================================
ATSinfo                                                             *ATSinfo*

  Description

atsinfo reads data out of the header of an ATS file.

  Syntax

idata ATSinfo iatsfile, ilocation

  Initialization

iatsfile – the ATS number (n in ats.n) or the name in quotes of the
analysis file made using ATS.

ilocation – indicates which location in the header file to return. The
data in the header gives information about the data contained in the
rest of the ATS file. The possible values for ilocation are given in the
following list:

0 - Sample rate (Hz)

1 - Frame Size (samples)

2 - Window Size (samples)

3 - Number of Partials

4 - Number of Frames

5 - Maximum Amplitude

6 - Maximum Frequency (Hz)

7 - Duration (seconds)

8 - ATS file Type

  Performance

Macros can really improve the legibility of your csound code, I've
provided my Macro Definitions below:

            #define ATS_SAMP_RATE #0#
            #define ATS_FRAME_SZ #1#
            #define ATS_WIN_SZ #2#
            #define ATS_N_PARTIALS #3#
            #define ATS_N_FRAMES #4#
            #define ATS_AMP_MAX #5#
            #define ATS_FREQ_MAX #6#
            #define ATS_DUR #7#
            #define ATS_TYPE #8#

ATSinfo can be useful for writing generic instruments that will work
with many ATS files, even if they have different lengths and different
numbers of partials etc. Example 2 is a simple application of this.


===========================================================================
ATSinterpread                                                 *ATSinterpread*

  Description

ATSinterpread allows a user to determine the frequency envelope of any
ATSbufread.

  Syntax

kamp ATSinterpread kfreq

  Performance

kfreq - a frequency value (given in Hertz) used by ATSinterpread as in
index into the table produced by an ATSbufread.

ATSinterpread takes a frequency value (kfreq in Hz). This frequency is
used to index the data of an ATSbufread. The return value is an
amplitude gained from the ATSbufread after interpolation. ATSinterpread
allows a user to determine the frequency envelope of any ATSbufread.
This data could be useful for an number of reasons, one might be
performing cross synthesis of data from an ATS file and non ATS data.


===========================================================================
ATSread                                                             *ATSread*

  Description

ATSread returns the amplitude (kamp) and frequency (kfreq) information
of a user specified partial contained in the ATS analysis file at the
time indicated by the time pointer ktimepnt.

  Syntax

kfreq, kamp ATSread ktimepnt, iatsfile, ipartial

  Initialization

iatsfile – the ATS number (n in ats.n) or the name in quotes of the
analysis file made using ATS.

ipartial – the number of the analysis partial to return the frequency in
Hz and amplitude.

  Performance

kfreq, kamp - outputs of the ATSread unit. These values represent the
frequency and amplitude of a specific partial selected by the user using
ipartial. The partials' informations are derived from an ATS analysis.
ATSread linearly interpolates the frequency and amplitude between frames
in the ATS analysis file at k-rate. The output is dependent on the data
in the analysis file and the pointer ktimepnt.

ktimepnt – The time pointer in seconds used to index the ATS file. Used
for ATSread exactly the same as for pvoc and ATSadd.


===========================================================================
ATSreadnz                                                         *ATSreadnz*

  Description

ATSreadnz returns the energy (kenergy) of a user specified noise band
(1-25 bands) at the time indicated by the time pointer ktimepnt.

  Syntax

kenergy ATSreadnz ktimepnt, iatsfile, iband

  Initialization

iatsfile – the ATS number (n in ats.n) or the name in quotes of the
analysis file made using ATS.

iband – the number of the noise band to return the energy data.

  Performance

kenergy outputs the linearly interpolated energy of the noise band
indicated in iband. The output is dependent on the data in the analysis
file and the ktimepnt.

ktimepnt – The time pointer in seconds used to index the ATS file. Used
for ATSreadnz exactly the same as for pvoc and ATSadd.

ATSaddnz reads from an ATS file and resynthesizes the noise from noise
energy data contained in the ATS file. It uses a modified randi function
to create band limited noise and modulates that with a user supplied
wave table (one period of a cosine wave), to synthesize a user specified
selection of frequency bands. Modulating the noise is required to put
the band limited noise in the correct place in the frequency spectrum.

An ATS analysis differs from a pvanal in that ATS tracks the partials
and computes the noise energy of the sound being analyzed. For more info
about ATS analysis read Juan Pampin's description on the the ATS web-page.


===========================================================================
ATSpartialtap                                                 *ATSpartialtap*

  Description

ATSpartialtap takes a partial number and returns a frequency, amplitude
pair. The frequency and amplitude data comes from an ATSbufread opcode.

  Syntax

kfrq, kamp ATSpartialtap ipartialnum

  Initialization

ipartialnum - indicates the partial that the ATSpartialtap opcode should
read from an ATSbufread.

  Performance

kfrq - returns the frequency value for the requested partial.

kamp - returns the amplitude value for the requested partial.

ATSpartialtap takes a partial number and returns a frequency, amplitude
pair. The frequency and amplitude data comes from an ATSbufread opcode.
This is more restricted version of ATSread, since each ATSread opcode
has its own independent time pointer, and ATSpartialtap is restricted to
the data given by an ATSbufread. Its simplicity is its attractive feature.


===========================================================================
ATSsinnoi                                                         *ATSsinnoi*

  Description

ATSsinnoi reads data from an ATS data file and uses the information to
synthesize sines and noise together.

  Syntax

ar ATSsinnoi ktimepnt, ksinlev, knzlev, kfmod, iatsfile, ipartials \
          [, ipartialoffset, ipartialincr]

  Initialization

iatsfile – the ATS number (n in ats.n) or the name in quotes of the
analysis file made using ATS.

ipartials – number of partials that will be used in the resynthesis (the
noise has a maximum of 25 bands)

ipartialoffset (optional) – is the first partial used (defaults to 0).

ipartialincr (optional) – sets an increment by which these synthesis
opcodes counts up from ipartialoffset for ibins components in the
re-synthesis (defaults to 1).

  Performance

ktimepnt – The time pointer in seconds used to index the ATS file. Used
for ATSsinnoi exactly the same as for pvoc.

ksinlev - controls the level of the sines in the ATSsinnoi ugen. A value
of 1 gives full volume sinewaves.

knzlev - controls the level of the noise components in the ATSsinnoi
ugen. A value of 1 gives full volume noise.

kfmod – an input for performing pitch transposition or frequency
modulation on all of the synthesized partials, if no fm or pitch change
is desired then use a 1 for this value.

ATSsinnoi reads data from an ATS data file and uses the information to
synthesize sines and noise together. The noise energy for each band is
distributed equally among each partial that falls in that band. Each
partial is then synthesized, along with that partial's noise component.
Each noise component is then modulated by the corresponding partial to
be put in the correct place in the frequency spectrum. The level of the
noise and the partials are individually controllable. See the ATS
webpage for more info about the sinnoi synthesis. An ATS analysis
differs from a pvanal in that ATS tracks the partials and computes the
noise energy of the sound being analyzed. For more info about ATS
analysis read Juan Pampin's description on the the ATS web-page.


===========================================================================
babo                                                                   *babo*

  Description

babo stands for ball-within-the-box. It is a physical model reverberator
based on the paper by Davide Rocchesso "The Ball within the Box: a
sound-processing metaphor", Computer Music Journal, Vol 19, N.4,
pp.45-47, Winter 1995.

The resonator geometry can be defined, along with some response
characteristics, the position of the listener within the resonator, and
the position of the sound source.

  Syntax

a1, a2 babo asig, ksrcx, ksrcy, ksrcz, irx, iry, irz [, idiff] [, ifno]

  Initialization

irx, iry, irz -- the coordinates of the geometry of the resonator
(length of the edges in meters)

idiff -- is the coefficient of diffusion at the walls, which regulates
the amount of diffusion (0-1, where 0 = no diffusion, 1 = maximum
diffusion - default: 1)

ifno -- expert values function: a function number that holds all the
additional parameters of the resonator. This is typically a GEN2--type
function used in non-rescaling mode. They are as follows:

  * decay -- main decay of the resonator (default: 0.99)

  * hydecay -- high frequency decay of the resonator (default: 0.1)

  * rcvx, rcvy, rcvz -- the coordinates of the position of the receiver
    (the listener) (in meters; 0,0,0 is the resonator center)

  * rdistance -- the distance in meters between the two pickups (your
    ears, for example - default: 0.3)

  * direct -- the attenuation of the direct signal (0-1, default: 0.5)

  * early_diff -- the attenuation coefficient of the early reflections
    (0-1, default: 0.8)

  Performance

asig -- the input signal

ksrcx, ksrcy, ksrcz -- the virtual coordinates of the source of sound
(the input signal). These are allowed to move at k-rate and provide all
the necessary variations in terms of response of the resonator.


===========================================================================
balance                                                             *balance*

  Description

The rms power of asig can be interrogated, set, or adjusted to match
that of a comparator signal.

  Syntax

ares balance asig, acomp [, ihp] [, iskip]

  Initialization

ihp (optional) -- half-power point (in Hz) of a special internal
low-pass filter. The default value is 10.

iskip (optional, default=0) -- initial disposition of internal data
space (see reson). The default value is 0.

  Performance

asig -- input audio signal

acomp -- the comparator signal

balance outputs a version of asig, amplitude-modified so that its rms
power is equal to that of a comparator signal acomp. Thus a signal that
has suffered loss of power (eg., in passing through a filter bank) can
be restored by matching it with, for instance, its own source. It should
be noted that gain and balance provide amplitude modification only -
output signals are not altered in any other respect.


===========================================================================
bamboo                                                               *bamboo*

  Description

bamboo is a semi-physical model of a bamboo sound. It is one of the
PhISEM percussion opcodes. PhISEM (Physically Informed Stochastic Event
Modeling) is an algorithmic approach for simulating collisions of
multiple independent sound producing objects.

  Syntax

ares bamboo kamp, idettack [, inum] [, idamp] [, imaxshake] [, ifreq] \
      [, ifreq1] [, ifreq2]

  Initialization

idettack -- period of time over which all sound is stopped

inum (optional) -- The number of beads, teeth, bells, timbrels, etc. If
zero, the default value is 1.25.

idamp (optional) -- the damping factor, as part of this equation:

damping_amount = 0.9999 + (idamp * 0.002)

The default damping_amount is 0.9999 which means that the default value
of idamp is 0. The maximum damping_amount is 1.0 (no damping). This
means the maximum value for idamp is 0.05.

The recommended range for idamp is usually below 75% of the maximum value.

imaxshake (optional, default=0) -- amount of energy to add back into the
system. The value should be in range 0 to 1.

ifreq (optional) -- the main resonant frequency. The default value is 2800.

ifreq1 (optional) -- the first resonant frequency. The default value is
2240.

ifreq2 (optional) -- the second resonant frequency. The default value is
3360.

  Performance

kamp -- Amplitude of output. Note: As these instruments are stochastic,
this is only an approximation.


===========================================================================
barmodel                                                           *barmodel*

  Description

Audio output is a tone similar to a struck metal bar, using a physical
model developed from solving the partial differential equation. There
are controls over the boundary conditions as well as the bar
characteristics.

  Syntax

ares barmodel kbcL, kbcR, iK, ib, kscan, iT30, ipos, ivel, iwid

  Initialization

iK -- dimensionless stiffness parameter. If this parameter is negative
then the initialisation is skipped and the previous state of the bar is
continued.

ib -- high-frequency loss parameter (keep this small).

iT30 -- 30 db decay time in seconds.

ipos -- position along the bar that the strike occurs.

ivel -- normalized strike velocity.

iwid -- spatial width of strike.

  Performance

A note is played on a metalic bar, with the arguments as below.

kbcL -- Boundary condition at left end of bar (1 is clamped, 2 pivoting
and 3 free).

kbcR -- Boundary condition at right end of bar (1 is clamped, 2 pivoting
and 3 free).

kscan -- Speed of scanning the output location.

Note that changing the boundary conditions during playing may lead to
glitches and is made available as an experiment. The use of a non-zero
kscan can give apparent re-introduction of sound due to modulation.


===========================================================================
bbcutm                                                               *bbcutm*

  Description

The BreakBeat Cutter automatically generates cut-ups of a source audio
stream in the style of drum and bass/jungle breakbeat manipulations.
There are two versions, for mono (bbcutm) or stereo (bbcuts) sources.
Whilst originally based on breakbeat cutting, the opcode can be applied
to any type of source audio.

The prototypical cut sequence favoured over one bar with eighth note
subdivisions would be

3+ 3R + 2

where we take a 3 unit block from the source's start, repeat it, then 2
units from the 7th and 8th eighth notes of the source.

We talk of rendering phrases (a sequence of cuts before reaching a new
phrase at the beginning of a bar) and units (as subdivision th notes).

The opcode comes most alive when multiple synchronised versions are used
simultaneously.

  Syntax

a1 bbcutm asource, ibps, isubdiv, ibarlength, iphrasebars, inumrepeats \
      [, istutterspeed] [, istutterchance] [, ienvchoice ]

  Initialization

ibps -- Tempo to cut at, in beats per second.

isubdiv -- Subdivisions unit, for a bar. So 8 is eighth notes (of a 4/4
bar).

ibarlength -- How many beats per bar. Set to 4 for default 4/4 bar
behaviour.

iphrasebars -- The output cuts are generated in phrases, each phrase is
up to iphrasebars long

inumrepeats -- In normal use the algorithm would allow up to one
additional repeat of a given cut at a time. This parameter allows that
to be changed. Value 1 is normal- up to one extra repeat. 0 would avoid
repeating, and you would always get back the original source except for
enveloping and stuttering.

istutterspeed -- (optional, default=1) The stutter can be an integer
multiple of the subdivision speed. For instance, if subdiv is 8
(quavers) and stutterspeed is 2, then the stutter is in semiquavers
(sixteenth notes= subdiv 16). The default is 1.

istutterchance -- (optional, default=0) The tail of a phrase has this
chance of becoming a single repeating one unit cell stutter (0.0 to
1.0). The default is 0.

ienvchoice -- (optional, default=1) choose 1 for on (exponential
envelope for cut grains) or 0 for off. Off will cause clicking, but may
give good noisy results, especially for percussive sources. The default
is 1, on.

  Performance

asource -- The audio signal to be cut up. This version runs in real-time
without knowledge of future audio.


===========================================================================
bbcuts                                                               *bbcuts*

  Description

The BreakBeat Cutter automatically generates cut-ups of a source audio
stream in the style of drum and bass/jungle breakbeat manipulations.
There are two versions, for mono (bbcutm) or stereo (bbcuts) sources.
Whilst originally based on breakbeat cutting, the opcode can be applied
to any type of source audio.

The prototypical cut sequence favoured over one bar with eighth note
subdivisions would be

3+ 3R + 2

where we take a 3 unit block from the source's start, repeat it, then 2
units from the 7th and 8th eighth notes of the source.

We talk of rendering phrases (a sequence of cuts before reaching a new
phrase at the beginning of a bar) and units (as subdivision th notes).

The opcode comes most alive when multiple synchronised versions are used
simultaneously.

  Syntax

a1,a2 bbcuts asource1, asource2, ibps, isubdiv, ibarlength, iphrasebars, \
      inumrepeats [, istutterspeed] [, istutterchance] [, ienvchoice]

  Initialization

ibps -- Tempo to cut at, in beats per second.

isubdiv -- Subdivisions unit, for a bar. So 8 is eighth notes (of a 4/4
bar).

ibarlength -- How many beats per bar. Set to 4 for default 4/4 bar
behaviour.

iphrasebars -- The output cuts are generated in phrases, each phrase is
up to iphrasebars long

inumrepeats -- In normal use the algorithm would allow up to one
additional repeat of a given cut at a time. This parameter allows that
to be changed. Value 1 is normal- up to one extra repeat. 0 would avoid
repeating, and you would always get back the original source except for
enveloping and stuttering.

istutterspeed -- (optional, default=1) The stutter can be an integer
multiple of the subdivision speed. For instance, if subdiv is 8
(quavers) and stutterspeed is 2, then the stutter is in semiquavers
(sixteenth notes= subdiv 16). The default is 1.

istutterchance -- (optional, default=0) The tail of a phrase has this
chance of becoming a single repeating one unit cell stutter (0.0 to
1.0). The default is 0.

ienvchoice -- (optional, default=1) choose 1 for on (exponential
envelope for cut grains) or 0 for off. Off will cause clicking, but may
give good noisy results, especially for percussive sources. The default
is 1, on.

  Performance

asource -- The audio signal to be cut up. This version runs in real-time
without knowledge of future audio.


===========================================================================
betarand                                                           *betarand*

  Description

Beta distribution random number generator (positive values only). This
is an x-class noise generator.

  Syntax

ares betarand krange, kalpha, kbeta

ires betarand krange, kalpha, kbeta

kres betarand krange, kalpha, kbeta

  Performance

krange -- range of the random numbers (0 - krange).

kalpha -- alpha value. If kalpha is smaller than one, smaller values
favor values near 0.

kbeta -- beta value. If kbeta is smaller than one, smaller values favor
values near krange.

If both kalpha and kbeta equal one we have uniform distribution. If both
kalpha and kbeta are greater than one we have a sort of Gaussian
distribution. Outputs only positive numbers.

For more detailed explanation of these distributions, see:

 1. C. Dodge - T.A. Jerse 1985. Computer music. Schirmer books. pp.265 - 286

 2. D. Lorrain. A panoply of stochastic cannons. In C. Roads, ed. 1989.
    Music machine . Cambridge, Massachusetts: MIT press, pp. 351 - 379.


===========================================================================
bexprnd                                                             *bexprnd*

  Description

Exponential distribution random number generator. This is an x-class
noise generator.

  Syntax

ares bexprnd krange

ires bexprnd krange

kres bexprnd krange

  Performance

krange -- the range of the random numbers (-krange to +krange)

For more detailed explanation of these distributions, see:

 1. C. Dodge - T.A. Jerse 1985. Computer music. Schirmer books. pp.265 - 286

 2. D. Lorrain. A panoply of stochastic cannons. In C. Roads, ed. 1989.
    Music machine . Cambridge, Massachusetts: MIT press, pp. 351 - 379.


===========================================================================
bformenc1                                                         *bformenc1*

  Description

Codes a signal into the ambisonic B format

  Syntax

aw, ax, ay, az bformenc1 asig, kalpha, kbeta

aw, ax, ay, az, ar, as, at, au, av bformenc1 asig, kalpha, kbeta

aw, ax, ay, az, ar, as, at, au, av, ak, al, am, an, ao, ap, aq bformenc1 \
      asig, kalpha, kbeta

aarray[] bformenc1 asig, kalpha, kbeta

  Performance

aw, ax, ay, ... -- output cells of the B format.

aarray -- output array to hold cells of the B format.

asig -- input signal.

kalpha –- azimuth angle in degrees (anticlockwise).

kbeta -- altitude angle in degrees.


===========================================================================
bformdec1                                                         *bformdec1*

  Description

Decodes an ambisonic B format signal into loudspeaker specific signals.

  Syntax

ao1, ao2 bformdec1 isetup, aw, ax, ay, az [, ar, as, at, au, av \
      [, abk, al, am, an, ao, ap, aq]]

ao1, ao2, ao3, ao4 bformdec1 isetup, aw, ax, ay, az [, ar, as, at, \
      au, av [, abk, al, am, an, ao, ap, aq]]

ao1, ao2, ao3, ao4, ao5 bformdec1 isetup, aw, ax, ay, az [, ar, as, \
      at, au, av [, abk, al, am, an, ao, ap, aq]]

ao1, ao2, ao3, ao4, ao5, ao6, ao7, ao8 bformdec1 isetup, aw, ax, ay, az \
      [, ar, as, at, au, av [, abk, al, am, an, ao, ap,
    aq]]]

aout[] bformdec1 isetup, abform[]

  Initialization

Note that horizontal angles are measured anticlockwise in this description.

isetup –- loudspeaker setup. There are five supported setups:

  * 1. Stereo - L(90), R(-90); this is an M+S style stereo decode.
  * 2. Quad - FL(45), BL(135), BR(-135), FR(-45). This is a first-order
    `in-phase' decode.
  * 3. 5.0 - L(30),R(-30),C(0),BL(110),BR(-110). Note that many people
    do not actually use the angles above for their speaker arrays and a
    good decode for DVD etc can be achieved using the Quad configuration
    to feed L, R, BL and BR (leaving C silent).
  * 4. Octagon -
    FFL(22.5),FLL(67.5),BLL(112.5),BBL(157.5),BBR(-157.5),BRR(-112.5),FRR(-67.5),FFR(-22.5).
    This is a first-, second- or third-order `in-phase' decode,
    depending on the number of input channels.
  * 5. Cube -
    FLD(45,-35.26),FLU(45,35.26),BLD(135,-35.26),BLU(135,35.26),BRD(-135,-35.26),BRU(-135,35.26),FRD(-45,-35.26),FRU(-45,35.26).
    This is a first-order `in-phase' decode.

  Performance

aw, ax, ay, ... -- input signal in the B format.

ao1 .. ao8 -– loudspeaker specific output signals.


===========================================================================
binit                                                                 *binit*

  Description

The binit opcode takes an input containg a TRACKS pv streaming signal
(as generated, for instance by partials) and converts it into a
equal-bandwidth bin-frame containing amplitude and frequency pairs
(PVS_AMP_FREQ), suitable for overlap-add resynthesis (such as performed
by pvsynth) or further PVS streaming phase vocoder signal
transformations. For each frequency bin, it will look for a suitable
track signal to fill it; if not found, the bin will be empty (0
amplitude). If more than one track fits a certain bin, the one with
highest amplitude will be chosen. This means that not all of the input
signal is actually 'binned', the operation is lossy. However, in many
situations this loss is not perceptually relevant.

  Syntax

fsig binit fin, isize

  Performance

fsig -- output pv stream in PVS_AMP_FREQ format

fin -- input pv stream in TRACKS format

isize -- FFT size of output (N).


===========================================================================
biquad                                                               *biquad*

  Description

A sweepable general purpose biquadratic digital filter.

  Syntax

ares biquad asig, kb0, kb1, kb2, ka0, ka1, ka2 [, iskip]

  Initialization

iskip (optional, default=0) -- if non-zero, intialization will be
skipped. Default value 0. (New in Csound version 3.50)

  Performance

asig -- input signal

biquad is a general purpose biquadratic digital filter of the form:

  a0*y(n) + a1*y[n-1] + a2*y[n-2] = b0*x[n] + b1*x[n-1] + b2*x[n-2]

This filter has the following frequency response:

         B(Z)   b0 + b1*Z^-1   + b2*Z^-2
  H(Z) = ---- = ------------------
         A(Z)   a0 + a1*Z^-1   + a2*Z^-2

This type of filter is often encountered in digital signal processing
literature. It allows six user-defined k-rate coefficients.


===========================================================================
biquada                                                             *biquada*

  Description

A sweepable general purpose biquadratic digital filter.

  Syntax

ares biquada asig, ab0, ab1, ab2, aa0, aa1, aa2 [, iskip]

  Initialization

iskip (optional, default=0) -- if non-zero, intialization will be
skipped. Default value 0. (New in Csound version 3.50)

  Performance

asig -- input signal

biquada is a general purpose biquadratic digital filter of the form:

  a0*y(n) + a1*y[n-1] + a2*y[n-2] = b0*x[n] + b1*x[n-1] + b2*x[n-2]

This filter has the following frequency response:

         B(Z)   b0 + b1*Z^-1   + b2*Z^-2
  H(Z) = ---- = ------------------
         A(Z)   a0 + a1*Z^-1   + a2*Z^-2

This type of filter is often encountered in digital signal processing
literature. It allows six user-defined a-rate coefficients.


===========================================================================
birnd                                                                 *birnd*

  Description

Returns a random number in a bi-polar range.

  Syntax

birnd(x) (init- or control-rate only)

Where the argument within the parentheses may be an expression. These
value converters sample a global random sequence, but do not reference
seed. The result can be a term in a further expression.

  Performance

Returns a random number in the bipolar range -x to x. rnd and birnd
obtain values from a global pseudo-random number generator, then scale
them into the requested range. The single global generator will thus
distribute its sequence to these units throughout the performance, in
whatever order the requests arrive.


===========================================================================
bqrez                                                                 *bqrez*

  Description

A second-order multi-mode filter.

  Syntax

ares bqrez asig, xfco, xres [, imode] [, iskip]

  Initialization

imode (optional, default=0) -- The mode of the filter. Choose from one
of the following:

  * 0 = low-pass (default)

  * 1 = high-pass

  * 2 = band-pass

  * 3 = band-reject

  * 4 = all-pass

iskip (optional, default=0) -- if non zero skip the initialisation of
the filter. (New in Csound version 4.23f13 and 5.0)

  Performance

ares -- output audio signal.

asig -- input audio signal.

xfco -- filter cut-off frequency in Hz. May be i-time, k-rate, a-rate.

xres -- amount of resonance. Values of 1 to 100 are typical. Resonance
should be one or greater. A value of 100 gives a 20dB gain at the cutoff
frequency. May be i-time, k-rate, a-rate.

All filter modes can be frequency modulated as well as the resonance can
also be frequency modulated.

bqrez is a resonant low-pass filter created using the Laplace s-domain
equations for low-pass, high-pass, and band-pass filters normalized to a
frequency. The bi-linear transform was used which contains a frequency
transform constant from s-domain to z-domain to exactly match the
frequencies together. Alot of trigonometric identities where used to
simplify the calculation. It is very stable across the working frequency
range up to the Nyquist frequency.


===========================================================================
butbp                                                                 *butbp*

  Description

Same as the butterbp opcode.

  Syntax

ares butbp asig, kfreq, kband [, iskip]

===========================================================================
butbr                                                                 *butbr*

  Description

Same as the butterbr opcode.

  Syntax

ares butbr asig, kfreq, kband [, iskip]

===========================================================================
buthp                                                                 *buthp*

  Description

Same as the butterhp opcode.

  Syntax

ares buthp asig, kfreq [, iskip]

ares buthp asig, afreq [, iskip]

===========================================================================
butlp                                                                 *butlp*

  Description

Same as the butterlp opcode.

  Syntax

ares butlp asig, kfreq [, iskip]

ares butlp asig, afreq [, iskip]

===========================================================================
butterbp                                                           *butterbp*

  Description

Implementation of a second-order band-pass Butterworth filter. This
opcode can also be written as butbp.

  Syntax

ares butterbp asig, xfreq, xband [, iskip]

  Initialization

iskip (optional, default=0) -- Skip initialization if present and non-zero.

  Performance

These filters are Butterworth second-order IIR filters. They are
slightly slower than the original filters in Csound, but they offer an
almost flat passband and very good precision and stopband attenuation.

asig -- Input signal to be filtered.

xfreq -- Cutoff or center frequency for each of the filters.

xband -- Bandwidth of the bandpass and bandreject filters.


===========================================================================
butterbr                                                           *butterbr*

  Description

Implementation of a second-order band-reject Butterworth filter. This
opcode can also be written as butbr.

  Syntax

ares butterbr asig, xfreq, xband [, iskip]

  Initialization

iskip (optional, default=0) -- Skip initialization if present and non-zero.

  Performance

These filters are Butterworth second-order IIR filters. They are
slightly slower than the original filters in Csound, but they offer an
almost flat passband and very good precision and stopband attenuation.

asig -- Input signal to be filtered.

xfreq -- Cutoff or center frequency for each of the filters.

xband -- Bandwidth of the bandpass and bandreject filters.


===========================================================================
butterhp                                                           *butterhp*

  Description

Implementation of second-order high-pass Butterworth filter. This opcode
can also be written as buthp.

  Syntax

ares butterhp asig, kfreq [, iskip]

ares butterhp asig, afreq [, iskip]

  Initialization

iskip (optional, default=0) -- Skip initialization if present and non-zero.

  Performance

These filters are Butterworth second-order IIR filters. They are
slightly slower than the original filters in Csound, but they offer an
almost flat passband and very good precision and stopband attenuation.

asig -- Input signal to be filtered.

kfreq/afreq -- Cutoff or center frequency for each of the filters.


===========================================================================
butterlp                                                           *butterlp*

  Description

Implementation of a second-order low-pass Butterworth filter. This
opcode can also be written as butlp.

  Syntax

ares butterlp asig, kfreq [, iskip]

ares butterlp asig, afreq [, iskip]

  Initialization

iskip (optional, default=0) -- Skip initialization if present and non-zero.

  Performance

These filters are Butterworth second-order IIR filters. They are
slightly slower than the original filters in Csound, but they offer an
almost flat passband and very good precision and stopband attenuation.

asig -- Input signal to be filtered.

kfreq/afreq -- Cutoff or center frequency for each of the filters.


===========================================================================
button                                                               *button*

  Description

Sense on-screen controls. Requires Winsound or TCL/TK.

  Syntax

kres button knum

  Performance

Note that this opcode is not available on Windows due to the
implimentation of pipes on that system

kres -- value of the button control. If the button has been pushed since
the last k-period, then return 1, otherwise return 0.

knum -- the number of the button. If it does not exist, it is made
on-screen at initialization.


===========================================================================
buzz                                                                   *buzz*

  Description

Output is a set of harmonically related sine partials.

  Syntax

ares buzz xamp, xcps, knh, ifn [, iphs]

  Initialization

ifn -- table number of a stored function containing a sine wave. A large
table of at least 8192 points is recommended.

iphs (optional, default=0) -- initial phase of the fundamental
frequency, expressed as a fraction of a cycle (0 to 1). A negative value
will cause phase initialization to be skipped. The default value is zero

  Performance

xamp -- amplitude

xcps -- frequency in cycles per second

The buzz units generate an additive set of harmonically related cosine
partials of fundamental frequency xcps, and whose amplitudes are scaled
so their summation peak equals xamp. The selection and strength of
partials is determined by the following control parameters:

knh -- total number of harmonics requested. New in Csound version 3.57,
knh defaults to one. If knh is negative, the absolute value is used.

buzz and gbuzz are useful as complex sound sources in subtractive
synthesis. buzz is a special case of the more general gbuzz in which klh
= kmul = 1; it thus produces a set of knh equal-strength harmonic
partials, beginning with the fundamental. (This is a band-limited pulse
train; if the partials extend to the Nyquist, i.e. knh = int (sr / 2 /
fundamental freq.), the result is a real pulse train of amplitude xamp.)

Although knh may be varied during performance, its internal value is
necessarily integer and may cause “pops” due to discontinuities in the
output. buzz can be amplitude- and/or frequency-modulated by either
control or audio signals.

N.B. This unit has its analog in GEN11, in which the same set of cosines
can be stored in a function table for sampling by an oscillator.
Although computationally more efficient, the stored pulse train has a
fixed spectral content, not a time-varying one as above.


===========================================================================
c2r                                                                     *c2r*

  Description

Converts a complex-valued input array into a real-valued array, by
removing its imaginary part. The output array will be halt the size of
the input. This is a utility operation to facilitate complex-valued
operations where the result is purely real.

  Syntax

kout[] c2r kin[]

  Performance

kout[] -- output array containing the real-valued output. It will be
created if it does not exist.

kin[] -- input array containing the complex-valued real-imaginary input.


===========================================================================
cabasa                                                               *cabasa*

  Description

cabasa is a semi-physical model of a cabasa sound. It is one of the
PhISEM percussion opcodes. PhISEM (Physically Informed Stochastic Event
Modeling) is an algorithmic approach for simulating collisions of
multiple independent sound producing objects.

  Syntax

ares cabasa iamp, idettack [, inum] [, idamp] [, imaxshake]

  Initialization

iamp -- Amplitude of output. Note: As these instruments are stochastic,
this is only a approximation.

idettack -- period of time over which all sound is stopped

inum (optional) -- The number of beads, teeth, bells, timbrels, etc. If
zero, the default value is 512.

idamp (optional) -- the damping factor, as part of this equation:

damping_amount = 0.998 + (idamp * 0.002)

The default damping_amount is 0.997 which means that the default value
of idamp is -0.5. The maximum damping_amount is 1.0 (no damping). This
means the maximum value for idamp is 1.0.

The recommended range for idamp is usually below 75% of the maximum value.

imaxshake (optional) -- amount of energy to add back into the system.
The value should be in range 0 to 1.


===========================================================================
cauchy                                                               *cauchy*

  Description

Cauchy distribution random number generator. This is an x-class noise
generator.

  Syntax

ares cauchy kalpha

ires cauchy kalpha

kres cauchy kalpha

  Performance

kalpha -- controls the spread from zero (big kalpha = big spread).
Outputs both positive and negative numbers.

For more detailed explanation of these distributions, see:

 1. C. Dodge - T.A. Jerse 1985. Computer music. Schirmer books. pp.265 - 286

 2. D. Lorrain. A panoply of stochastic cannons. In C. Roads, ed. 1989.
    Music machine . Cambridge, Massachusetts: MIT press, pp. 351 - 379.


===========================================================================
cauchyi                                                             *cauchyi*

  Description

Cauchy distribution random number generator with controlled
interpolation between values. This is an x-class noise generator.

  Syntax

ares cauchyi klambda, xamp, xcps

ires cauchyi klambda, xamp, xcps

kres cauchyi klambda, xamp, xcps

  Performance

kalpha -- controls the spread from zero (big kalpha = big spread).
Outputs both positive and negative numbers.

For more detailed explanation of these distributions, see:

 1. C. Dodge - T.A. Jerse 1985. Computer music. Schirmer books. pp.265 - 286

 2. D. Lorrain. A panoply of stochastic cannons. In C. Roads, ed. 1989.
    Music machine . Cambridge, Massachusetts: MIT press, pp. 351 - 379.

xamp -- range over which random numbers are distributed.

xcps -- the frequency which new random numbers are generated.


===========================================================================
ceil                                                                   *ceil*

  Description

Returns the smallest integer not less than x

  Syntax

ceil(x) (init-, control-, or audio-rate arg allowed)

where the argument within the parentheses may be an expression. Value
converters perform arithmetic translation from units of one kind to
units of another. The result can then be a term in a further expression.


===========================================================================
cell                                                                   *cell*

  Description

One-Dimensional Cellular Automaton. This opcode is the modified version
of vcella by Gabriel Maldonado.

  Syntax

cell ktrig, kreinit, ioutFunc, initStateFunc, iRuleFunc, ielements

  Initialization

ioutFunc -- number of the table where the state of each cell is stored.

initStateFunc -- number of the table containing the inital states of cells.

iRuleFunc -- number of a lookup table containing the 8-bit rule.

ielements -- total number of cells in a row.

  Performance

ktri -- trigger signal. Each time it is non-zero, a new generation of
cells is evaluated.

kreinit -- reset signal. Each time it is non-zero, state of all cells is
forced to be that of initStateFunc.

cell models a classical 1D cellular automaton and stores the state of
each cell in the table identified by ioutFunc.

initStateFunc is an input vector containing the inital value of the row
of cells, while iRuleFunc is an input vector containing the chosen rule
in the binary form (least significant bit first).

A new generation of cells is evaluated each time ktrig contains a
non-zero value. Also the status of all cells can be forced to assume the
status corresponding to the contents of initStateFunc each time kreinit
contains a non-zero value.

Note that each cell is supposed to be in one of two possible states (1 =
"alive", 0 = "dead"), although fractional values should work too,
because truncation is used.


===========================================================================
cent                                                                   *cent*

  Description

Calculates a factor to raise/lower a frequency by a given amount of cents.

  Syntax

cent(x) 

This function works at a-rate, i-rate, and k-rate.

  Initialization

x -- a value expressed in cents.

  Performance

The value returned by the cent function is a factor. You can multiply a
frequency by this factor to raise/lower it by the given amount of cents.


===========================================================================
centroid                                                           *centroid*

  Description

Calculate the spectral centroid of an audio signal on a given trigger.

  Syntax

kcent centroid asig, ktrig, ifftsize

  Initialization

ifftsize -- fftsize. Non pow-of-two values are converted to the next
pow-of-two not smaller than ifftsize.

  Performance

kcent -- the spectral centroid in Hz

asig -- an input audio signal

ktrig -- 1 to calculate a new centroid, 0 to skip the process (and
output previous value).


===========================================================================
ceps                                                                   *ceps*

  Description

  Syntax

keps[] ceps kmags[][, icoefs]

  Initialization

icoefs -- the number of retained coefficients in the cepstrum output. By
default, no coefficients are liftered.

  Performance

keps[] -- the cepstrum output, an array of size N+1, where N is a power
of two.

kmags[] -- an input array containing N+1 magnitudes.


===========================================================================
cepsinv                                                             *cepsinv*

  Description

  Syntax

kenv cepsinv keps[]

  Performance

keps[] -- the cepstrum input, an array of size N+1, where N is
power-of-two, containing the cepstral coefficients.

kenv -- the inverse cepstrum (spectral envelope), an array of N+1
magnitudes.


===========================================================================
cggoto                                                               *cggoto*

  Description

Transfer control to label on every pass. (Combination of cigoto and ckgoto)

  Syntax

cggoto condition, label

where label is in the same instrument block and is not an expression,
and where condition uses one of the Relational operators (<,=, <=, ==,
!=) (and = for convenience, see also under Conditional Values).


===========================================================================
chanctrl                                                           *chanctrl*

  Description

Get the current value of a controller and optionally map it onto
specified range.

  Syntax

ival chanctrl ichnl, ictlno [, ilow] [, ihigh]

kval chanctrl ichnl, ictlno [, ilow] [, ihigh]

  Initialization

ichnl -- the MIDI channel (1-16).

ictlno -- the MIDI controller number (0-127).

ilow, ihigh -- low and high ranges for mapping


===========================================================================
changed                                                             *changed*

  Description

This opcode outputs a trigger signal that informs when any one of its
k-rate arguments has changed. Useful with valuator widgets or MIDI
controllers.

  Syntax

ktrig changed kvar1 [, kvar2,..., kvarN]

  Performance

ktrig - Outputs a value of 1 when any of the k-rate signals has changed,
otherwise outputs 0.

kvar1 [, kvar2,..., kvarN] - k-rate variables to watch for changes.

  Note
If any of the kvars is non-zero at the first k-cycle changed is called
it will report a change. For more consistent behaviour use changed2.


===========================================================================
changed2                                                           *changed2*

  Description

This opcode outputs a trigger signal that informs when any one of its
k-rate arguments has changed, or a value in an array. Useful with
valuator widgets or MIDI controllers.

  Syntax

ktrig changed2 kvar1 [, kvar2,..., kvarN]

ktrig changed2 karr[]

ktrig changed2 aarr[]

  Performance

ktrig - Outputs a value of 1 when any of the k-rate signals has changed,
or any value in the array, otherwise outputs 0.

kvar1 [, kvar2,..., kvarN] - k-rate variables to watch for changes.

xarray - any array type.

Unlike the opcode changed this opcode will ever report the first cycle
as a change.


===========================================================================
chani                                                                 *chani*

  Description

Reads data from a channel of the inward software bus.

  Syntax

kval chani kchan

aval chani kchan

  Performance

kchan -- a positive integer that indicates which channel of the software
bus to read

Note that the inward and outward software busses are independent, and
are not mixer buses. Also the k-rate and a-rate busses are independent.
The last value remains until a new value is written. There is no imposed
limit to the number of busses but they use memory so small numbers are
to be preferred.


===========================================================================
chano                                                                 *chano*

  Description

Send data to a channel of the outward software bus.

  Syntax

chano kval, kchan

chano aval, kchan

  Performance

xval --- value to transmit

kchan -- a positive integer that indicates which channel of the software
bus to write

Note that the inward and outward software busses are independent, and
are not mixer buses. Also the k-rate and a-rate busses are independent.
The last value remains until a new value is written. There is no imposed
limit to the number of busses but they use memory so small numbers are
to be preferred.


===========================================================================
chebyshevpoly                                                 *chebyshevpoly*

  Description

The chebyshevpoly opcode calculates the value of a polynomial expression
with a single a-rate input variable that is made up of a linear
combination of the first N Chebyshev polynomials of the first kind. Each
Chebyshev polynomial, Tn(x), is weighted by a k-rate coefficient, kn, so
that the opcode is calculating a sum of any number of terms in the form
kn*Tn(x). Thus, the chebyshevpoly opcode allows for the waveshaping of
an audio signal with a dynamic transfer function that gives precise
control over the harmonic content of the output.

  Syntax

aout chebyshevpoly ain, k0 [, k1 [, k2 [...]]]

  Performance

ain -- the input signal used as the independent variable of the
Chebyshev polynomials ("x").

aout -- the output signal ("y").

k0, k1, k2, ... -- k-rate multipliers for each Chebyshev polynomial.

This opcode is very useful for dynamic waveshaping of an audio signal.
Traditional waveshaping techniques utilize a lookup table for the
transfer function -- usually a sum of Chebyshev polynomials. When a sine
wave at full-scale amplitude is used as an index to read the table, the
precise harmonic spectrum as defined by the weights of the Chebyshev
polynomials is produced. A dynamic spectrum is acheived by varying the
amplitude of the input sine wave, but this produces a non-linear change
in the spectrum.

By directly calculating the Chebyshev polynomials, the chebyshevpoly
opcode allows more control over the spectrum and the number of harmonic
partials added to the input can be varied with time. The value of each
kn coefficient directly controls the amplitude of the nth harmonic
partial if the input ain is a sine wave with amplitude = 1.0. This makes
chebyshevpoly an efficient additive synthesis engine for N partials that
requires only one oscillator instead of N oscillators. The amplitude or
waveform of the input signal can also be changed for different
waveshaping effects.

If we consider the input parameter ain to be "x" and the output aout to
be "y", then the chebyshevpoly opcode calculates the following equation:

        y = k0*T0(x) + k1*T1(x) + k2*T2(x) + k3*T3(x) + ...

where the Tn(x) are defined by the recurrence relation

        T0(x) = 1,
        T1(x) = x, 
        Tn(x) = 2x*T[n-1](x) - T[n-2](x)

More information about Chebyshev polynomials can be found on Wikipedia
at http://en.wikipedia.org/wiki/Chebyshev_polynomial


===========================================================================
checkbox                                                           *checkbox*

  Description

Sense on-screen controls. Requires Winsound or TCL/TK.

  Syntax

kres checkbox knum

  Performance

Note that this opcode is not available on Windows due to the
implimentation of pipes on that system

kres -- value of the checkbox control. If the checkbox is set (pushed)
then return 1, if not, return 0.

knum -- the number of the checkbox. If it does not exist, it is made
on-screen at initialization.


===========================================================================
chn                                                                     *chn*

  Description

Declare a channel of the named software bus, with setting optional
parameters in the case of a control channel. If the channel does not
exist yet, it is created, with an inital value of zero or empty string.
Otherwise, the type (control, audio, or string) of the existing channel
must match the declaration, or an init error occurs. The input/output
mode of an existing channel is updated so that it becomes the bitwise OR
of the previous and the newly specified value.

  Syntax

 chn_k Sname, imode[, itype, idflt, imin, ima, ix, iy, iwidth, iheight, Sattributes]

 chn_a Sname, imode

 chn_S Sname, imode

  Initialization

imode -- sum of at least one of 1 for input and 2 for output.

itype (optional, defaults to 0) -- channel subtype for control channels
only. Possible values are:

  * 0: default/unspecified (idflt, imin, and imax are ignored)

  * 1: integer values only

  * 2: linear scale

  * 3: exponential scale

idflt (optional, defaults to 0) -- default value, for control channels
with non-zero itype only. Must be greater than or equal to imin, and
less than or equal to imax.

imin (optional, defaults to 0) -- minimum value, for control channels
with non-zero itype only. Must be non-zero for exponential scale (itype
= 3).

imax (optional, defaults to 0) -- maximum value, for control channels
with non-zero itype only. Must be greater than imin. In the case of
exponential scale, it should also match the sign of imin.

ix -- suggested x position for controller.

iy -- suggested y position for controller.

iwidth -- suggested width position for controller.

iheight -- suggested height position for controller.

Sattributes -- attributes for controller.

===========================================================================
Notes                                                                 *Notes*

The channel parameters (imode, itype, idflt, imin, and imax) are only
hints for the host application or external software accessing the bus
through the API, and do not actually restrict reading from or writing to
the channel in any way. Also, the initial value of a newly created
control channel is zero, regardless of the setting of idflt.

For communication with external software, using chnexport may be
preferred, as it allows direct access to orchestra variables exported as
channels of the bus, eliminating the need for using chnset and chnget to
send or receive data.

  Performance

chn_k, chn_a, and chn_S declare a control, audio, or string channel,
respectively.


===========================================================================
chnclear                                                           *chnclear*

  Description

Clears an audio channel of the named software bus to zero. Implies
declaring the channel with imode=2 (see also chn_a).

  Syntax

chnclear Sname

  Initialization

Sname -- a string that indicates which named channel of the software bus
to clear.


===========================================================================
chnexport                                                         *chnexport*

  Description

Export a global variable as a channel of the bus; the channel should not
already exist, otherwise an init error occurs. This opcode is normally
called from the orchestra header, and allows the host application to
read or write orchestra variables directly, without having to use chnget
or chnset to copy data.

  Syntax

gival chnexport Sname, imode[, itype, idflt, imin, imax]

gkval chnexport Sname, imode[, itype, idflt, imin, imax]

gaval chnexport Sname, imode

gSval chnexport Sname, imode

  Initialization

imode -- sum of at least one of 1 for input and 2 for output.

itype (optional, defaults to 0) -- channel subtype for control channels
only. Possible values are:

  * 0: default/unspecified (idflt, imin, and imax are ignored)

  * 1: integer values only

  * 2: linear scale

  * 3: exponential scale

idflt (optional, defaults to 0) -- default value, for control channels
with non-zero itype only. Must be greater than or equal to imin, and
less than or equal to imax.

imin (optional, defaults to 0) -- minimum value, for control channels
with non-zero itype only. Must be non-zero for exponential scale (itype
= 3).

imax (optional, defaults to 0) -- maximum value, for control channels
with non-zero itype only. Must be greater than imin. In the case of
exponential scale, it should also match the sign of imin.

Notes

The channel parameters (imode, itype, idflt, imin, and imax) are only
hints for the host application or external software accessing the bus
through the API, and do not actually restrict reading from or writing to
the channel in any way.

While the global variable is used as output argument, chnexport does not
actually change it, and always runs at i-time only. If the variable is
not previously declared, it is created by Csound with an initial value
of zero or empty string.


===========================================================================
chnget                                                               *chnget*

  Description

Reads data from a channel of the inward named software bus. Implies
declaring the channel with imode=1 (see also chn_k, chn_a, and chn_S).

  Syntax

ival chnget Sname

kval chnget Sname

aval chnget Sname

Sval chnget Sname

  Initialization

Sname -- a string that identifies a channel of the named software bus to
read.

ival -- the control value read at i-time.

Sval -- the string value read at i-time.

  Performance

kval -- the control value read at performance time.

aval -- the audio signal read at performance time.


===========================================================================
chnmix                                                               *chnmix*

  Description

Adds an audio signal to a channel of the named software bus. Implies
declaring the channel with imode=2 (see also chn_a).

  Syntax

chnmix aval, Sname

  Initialization

Sname -- a string that indicates which named channel of the software bus
to write.

  Performance

aval -- the audio signal to write at performance time.


===========================================================================
chnparams                                                         *chnparams*

  Description

Query parameters of a channel (if it does not exist, all returned values
are zero).

  Syntax

itype, imode, ictltype, idflt, imin, imax chnparams

  Initialization

itype -- channel data type (1: control, 2: audio, 3: string)

imode -- sum of 1 for input and 2 for output

ictltype -- special parameter for control channel only; if not
available, set to zero.

idflt -- special parameter for control channel only; if not available,
set to zero.

imin -- special parameter for control channel only; if not available,
set to zero.

imax -- special parameter for control channel only; if not available,
set to zero.


===========================================================================
chnset                                                               *chnset*

  Description

Write to a channel of the named software bus. Implies declaring the
channel with imod=2 (see also chn_k, chn_a, and chn_S).

  Syntax

chnset ival, Sname

chnset kval, Sname

chnset aval, Sname

chnset Sval, Sname

  Initialization

Sname -- a string that indicates which named channel of the software bus
to write.

ival -- the control value to write at i-time.

Sval -- the string value to write at i-time.

  Performance

kval -- the control value to write at performance time.

aval -- the audio signal to write at performance time.


===========================================================================
chuap                                                                 *chuap*

  Description

Simulates Chua's oscillator, an LRC oscillator with an active resistor,
proved capable of bifurcation and chaotic attractors, with k-rate
control of circuit elements.

  Syntax

aI3, aV2, aV1 chuap kL, kR0, kC1, kG, kGa, kGb, kE, kC2, iI3, iV2, iV1, ktime_step

  Initialization

iI3 -- Initial current at G

iV2 -- Initial voltage at C2

iV1 -- Initial voltage at C1

  Performance

kL -- Inductor L

kR0 -- Resistor R0

kC1 -- Capacitor C1

kG -- Resistor G

kGa -- Resistor V (nonlinearity term)

kGb -- Resistor V (nonlinearity term)

kGb -- Resistor V (nonlinearity term)

ktime_step -- Delta time in the difference equation, can be used to more
or less control pitch.

Chua's oscillator is a simple LRC oscillator with an active resistor.
The oscillator can be driven into period bifurcation, and thus to chaos,
because of the nonlinear response of the active resistor.

Diagram of Chua's Oscillator Circuit

The circuit is described by a set of three ordinary differential
equations called Chua's equations:

      dI3      R0      1
      --- =  - -- I3 - - V2
      dt       L       L

      dV2    1       G
      --- = -- I3 - -- (V2 - V1)
      dt    C2      C2

      dV1    G              1
      --- = -- (V2 - V1) - -- f(V1)
      dt    C1             C1

where f() is a piecewise discontinuity simulating the active resistor:

      f(V1) = Gb V1 + - (Ga - Gb)(|V1 + E| - |V1 - E|)

A solution of these equations (I3,V2,V1)(t) starting from an initial
state (I3,V2,V1)(0) is called a trajectory of Chua's oscillator. The
Csound implementation is a difference equation simulation of Chua's
oscillator with Runge-Kutta integration.

  Note

This algorithm uses internal non linear feedback loops which causes
audio result to depend on the orchestra sampling rate. For example, if
you develop a project with sr=48000Hz and if you want to produce an
audio CD from it, you should record a file with sr=48000Hz and then
downsample the file to 44100Hz using the srconv utility.

  Warning
Be careful! Some sets of parameters will produce amplitude spikes or
positive feedback that could damage your speakers.


===========================================================================
cigoto                                                               *cigoto*

  Description

During the i-time pass only, conditionally transfer control to the
statement labeled by label.

  Syntax

cigoto condition, label

where label is in the same instrument block and is not an expression,
and where condition uses one of the Relational operators (<,=, <=, ==,
!=) (and = for convenience, see also under Conditional Values).


===========================================================================
ckgoto                                                               *ckgoto*

  Description

During the p-time passes only, conditionally transfer control to the
statement labeled by label.

  Syntax

ckgoto condition, label

where label is in the same instrument block and is not an expression,
and where condition uses one of the Relational operators (<,=, <=, ==,
!=) (and = for convenience, see also under Conditional Values).


===========================================================================
clear                                                                 *clear*

  Description

clear zeroes a list of audio signals.

  Syntax

clear avar1 [, avar2] [, avar3] [...]

  Performance

avar1, avar2, avar3, ... -- signals to be zeroed

clear sets every sample of each of the given audio signals to zero when
it is performed. This is equivalent to writing avarN = 0 in the
orchestra for each of the specified variables. Typically, clear is used
with global variables that combine multiple signals from different
sources and change with each k-pass (performance loop) through all of
the active instrument instances. After the final usage of such a
variable and before the next k-pass, it is necessary to clear the
variable so that it does not add the next cycle's signals to the
previous result. clear is especially useful in combination with vincr
(variable increment) and they are intended to be used together with file
output opcodes such as fout.


===========================================================================
clfilt                                                               *clfilt*

  Description

Implements the classical standard analog filter types: low-pass and
high-pass. They are implemented with the four classical kinds of
filters: Butterworth, Chebyshev Type I, Chebyshev Type II, and
Elliptical. The number of poles may be any even number from 2 to 80.

  Syntax

ares clfilt asig, kfreq, itype, inpol [, ikind] [, ipbr] [, isba] [, iskip]

  Initialization

itype -- 0 for low-pass, 1 for high-pass.

inpol -- The number of poles in the filter. It must be an even number
from 2 to 80.

ikind (optional) -- 0 for Butterworth, 1 for Chebyshev Type I, 2 for
Chebyshev Type II, 3 for Elliptical. Defaults to 0 (Butterworth)

ipbr (optional) -- The pass-band ripple in dB. Must be greater than 0.
It is ignored by Butterworth and Chebyshev Type II. The default is 1 dB.

isba (optional) -- The stop-band attenuation in dB. Must be less than 0.
It is ignored by Butterworth and Chebyshev Type I. The default is -60 dB.

iskip (optional) -- 0 initializes all filter internal states to 0. 1
skips initialization. The default is 0.

  Performance

asig -- The input audio signal.

kfreq -- The corner frequency for low-pass or high-pass.


===========================================================================
clip                                                                   *clip*

  Description

Clips an a-rate signal to a predefined limit, in a “soft” manner, using
one of three methods.

  Syntax

ares clip asig, imeth, ilimit [, iarg]

  Initialization

imeth -- selects the clipping method. The default is 0. The methods are:

  * 0 = Bram de Jong method (default)

  * 1 = sine clipping

  * 2 = tanh clipping

ilimit -- limiting value

iarg (optional, default=0.5) -- when imeth = 0, indicates the point at
which clipping starts, in the range 0 - 1. Not used when imeth = 1 or
imeth = 2. Default is 0.5.

  Performance

asig -- a-rate input signal

The Bram de Jong method (imeth = 0) applies the algorithm (denoting
ilimit as limit and iarg as a):

|x| >= 0 and |x| <= (limit*a):  f(x) = f(x)
|x| > (limit*a) and |x| <= limit:  f(x) = sign(x) * (limit*a+(x-limit*a)/(1+((x-limit*a)/(limit*(1-a)))^2 ))
|x| > limit:  f(x) = sign(x) * (limit*(1+a))/2

The second method (imeth = 1) is the sine clip:

|x| < limit:  f(x) = limit * sin(π*x/(2*limit)),   |x| >= limit:  f(x) = limit * sign(x)

The third method (imeth = 2) is the tanh clip:

|x| < limit:  f(x) = limit * tanh(x/limit)/tanh(1),   |x| >= limit:  f(x) = limit * sign(x)

  Note

Method 1 appears to be non-functional at release of Csound version 4.07.


===========================================================================
clockoff                                                           *clockoff*

  Description

Stops one of a number of internal clocks.

  Syntax

clockoff inum

  Initialization

inum -- the number of a clock. There are 32 clocks numbered 0 through
31. All other values are mapped to clock number 32.

  Performance

Between a clockon and a clockoff opcode, the CPU time used is
accumulated in the clock. The precision is machine dependent but is the
millisecond range on UNIX and Windows systems. The readclock opcode
reads the current value of a clock at initialization time.


===========================================================================
clockon                                                             *clockon*

  Description

Starts one of a number of internal clocks.

  Syntax

clockon inum

  Initialization

inum -- the number of a clock. There are 32 clocks numbered 0 through
31. All other values are mapped to clock number 32.

  Performance

Between a clockon and a clockoff opcode, the CPU time used is
accumulated in the clock. The precision is machine dependent but is the
millisecond range on UNIX and Windows systems. The readclock opcode
reads the current value of a clock at initialization time.


===========================================================================
cmplxprod                                                         *cmplxprod*

  Description

Calculates the complex product of two arrays of the same size and in
real-imaginary interleaved format.

  Syntax

kout[] cmplxprod kin1[], kin2[]

  Performance

kout[] -- output array containing the product. It will be created if it
does not exist.

kin1[], kin2[] -- input arrays containing the complex inputs.


===========================================================================
cngoto                                                               *cngoto*

  Description

Transfers control on every pass when the condition is not true.

  Syntax

cngoto condition, label

where label is in the same instrument block and is not an expression,
and where condition uses one of the Relational operators (<,=, <=, ==,
!=) (and = for convenience, see also under Conditional Values).


===========================================================================
comb                                                                   *comb*

  Description

Reverberates an input signal with a “colored” frequency response.

  Syntax

ares comb asig, krvt, ilpt [, iskip] [, insmps]

  Initialization

ilpt -- loop time in seconds, which determines the “echo density” of the
reverberation. This in turn characterizes the “color” of the comb filter
whose frequency response curve will contain ilpt * sr/2 peaks spaced
evenly between 0 and sr/2 (the Nyquist frequency). Loop time can be as
large as available memory will permit. The space required for an n
second loop is n*sr floating or double numbers (usually 4 or 8 bytes).
Delay space is allocated and returned as in delay.

iskip (optional, default=0) -- initial disposition of delay-loop data
space (cf. reson). The default value is 0.

insmps (optional, default=0) -- delay amount, as a number of samples.

  Performance

krvt -- the reverberation time (defined as the time in seconds for a
signal to decay to 1/1000, or 60dB down from its original amplitude).

This filter reiterates input with an echo density determined by loop
time ilpt. The attenuation rate is independent and is determined by
krvt, the reverberation time (defined as the time in seconds for a
signal to decay to 1/1000, or 60dB down from its original amplitude).
Output from a comb filter will appear only after ilpt seconds.


===========================================================================
combinv                                                             *combinv*

  Description

Reverberates an input signal with a “colored” frequency response with a
FIR filter.

  Syntax

ares combinv asig, krvt, ilpt [, iskip] [, insmps]

  Initialization

ilpt -- loop time in seconds, which determines the “echo density” of the
reverberation. This in turn characterizes the “color” of the combinv
filter whose frequency response curve will contain ilpt * sr/2 peaks
spaced evenly between 0 and sr/2 (the Nyquist frequency). Loop time can
be as large as available memory will permit. The space required for an n
second loop is n*sr floating or double numbers (usually 4 or 8 bytes).
Delay space is allocated and returned as in delay.

iskip (optional, default=0) -- initial disposition of delay-loop data
space (cf. reson). The default value is 0.

insmps (optional, default=0) -- delay amount, as a number of samples.

  Performance

krvt -- the reverberation time (defined as the time in seconds for a
signal to decay to 1/1000, or 60dB down from its original amplitude).

This filter reiterates input with an echo density determined by loop
time ilpt. The attenuation rate is independent and is determined by
krvt, the reverberation time (defined as the time in seconds for a
signal to decay to 1/1000, or 60dB down from its original amplitude).
Affect from a combinv filter will appear only after ilpt seconds.


===========================================================================
compilecsd                                                       *compilecsd*

  Description

Compilecsd will read a CSD file and compile one or more instruments at
init time, which will be added to the running engine. In case of
existing instrument numbers or names, these will be replaced, but any
instance still running of the old instrument definition will still
perform until it terminates. In addition, it will read the score (if it
exists) contained in the CSD file and add it to the list of events to be
performed by Csound. The opcode ignores any section in the CSD file that
is not the orchestra or the score.

  Syntax

ires compilecsd Sfilename

  Initialization

“Sfilename” -- a string containing the name of the file containing the
orchestra.

“ires” -- returns 0 if compilation was successful, or -1 if not.


===========================================================================
compileorc                                                       *compileorc*

  Description

Compileorc will compile one or more instruments at init time, which will
be added to the running engine. In case of existing instrument numbers
or names, these will be replaced, but any instance still running of the
old instrument definition will still perform until it terminates.

  Syntax

ires compileorc Sfilename

  Initialization

“Sfilename” -- a string containing the name of the file containing the
orchestra.

“ires” -- returns 0 if compilation was successful, or -1 if not.


===========================================================================
compilestr                                                       *compilestr*

  Description

Compilestr will compile one or more instruments at init time, which will
be added to the running engine. In case of existing instrument numbers
or names, these will be replaced, but any instance still running of the
old instrument definition will still perform until it terminates. Only
new instances will use the new definition. Multi-line strings are
accepted, using {{ }} to enclose the string.

  Syntax

ires compilestr Sorch

  Initialization

“Sorch” -- a string (in double-quotes or enclosed by {{ }}) containing
one or more instruments.

“ires” -- returns 0 if compilation was successful, or -1 if not.


===========================================================================
compress                                                           *compress*

  Description

This unit functions as an audio compressor, limiter, expander, or noise
gate, using either soft-knee or hard-knee mapping, and with dynamically
variable performance characteristics. It takes two audio input signals,
aasig and acsig, the first of which is modified by a running analysis of
the second. Both signals can be the same, or the first can be modified
by a different controlling signal.

compress first examines the controlling acsig by performing envelope
detection. This is directed by two control values katt and krel,
defining the attack and release time constants (in seconds) of the
detector. The detector rides the peaks (not the RMS) of the control
signal. Typical values are .01 and .1, the latter usually being similar
to ilook.

The running envelope is next converted to decibels, then passed through
a mapping function to determine what compresser action (if any) should
be taken. The mapping function is defined by four decibel control
values. These are given as positive values, where 0 db corresponds to an
amplitude of 0dbfs/32768, and 90 db corresponds to an amplitude of 0dbfs.

  Syntax

ar compress aasig, acsig, kthresh, kloknee, khiknee, kratio, katt, krel, ilook

  Initialization

ilook -- lookahead time in seconds, by which an internal envelope
release can sense what is coming. This induces a delay between input and
output, but a small amount of lookahead improves the performance of the
envelope detector. Typical value is .05 seconds, sufficient to sense the
peaks of the lowest frequency in acsig.

  Performance

kthresh -- sets the lowest decibel level that will be allowed through.
Normally 0 or less, but if higher the threshold will begin removing
low-level signal energy such as background noise.

kloknee, khiknee -- decibel break-points denoting where compression or
expansion will begin. These set the boundaries of a soft-knee curve
joining the low-amplitude 1:1 line and the higher-amplitude compression
ratio line. Typical values are 48 and 60 db. If the two breakpoints are
equal, a hard-knee (angled) map will result.

kratio -- ratio of compression when the signal level is above the knee.
The value 2 will advance the output just one decibel for every input
gain of two; 3 will advance just one in three; 20 just one in twenty,
etc. Inverse ratios will cause signal expansion: .5 gives two for one,
.25 four for one, etc. The value 1 will result in no change.

The actions of compress will depend on the parameter settings given. A
hard-knee compressor-limiter, for instance, is obtained from a near-zero
attack time, equal-value break-points, and a very high ratio (say 100).
A noise-gate plus expander is obtained from some positive threshold, and
a fractional ratio above the knee. A voice-activated music compressor
(ducker) will result from feeding the music into aasig and the speech
into acsig. A voice de-esser will result from feeding the voice into
both, with the acsig version being preceded by a band-pass filter that
emphasizes the sibilants. Each application will require some
experimentation to find the best parameter settings; these have been
made k-variable to make this practical.


===========================================================================
compress2                                                         *compress2*

  Description

This unit functions as an audio compressor, limiter, expander, or noise
gate, using either soft-knee or hard-knee mapping, and with dynamically
variable performance characteristics. It takes two audio input signals,
aasig and acsig, the first of which is modified by a running analysis of
the second. Both signals can be the same, or the first can be modified
by a different controlling signal.

compress2 first examines the controlling acsig by performing envelope
detection. This is directed by two control values katt and krel,
defining the attack and release time constants (in seconds) of the
detector. The detector rides the peaks (not the RMS) of the control
signal. Typical values are .01 and .1, the latter usually being similar
to ilook.

The running envelope is next converted to decibels, then passed through
a mapping function to determine what compresser action (if any) should
be taken. The mapping function is defined by four decibel control
values. These are given as positive values, where 0 db corresponds to an
amplitude of 0dbfs.

  Syntax

ar compress2 aasig, acsig, kthresh, kloknee, khiknee, kratio, katt, krel, ilook

  Initialization

ilook -- lookahead time in seconds, by which an internal envelope
release can sense what is coming. This induces a delay between input and
output, but a small amount of lookahead improves the performance of the
envelope detector. Typical value is .05 seconds, sufficient to sense the
peaks of the lowest frequency in acsig.

  Performance

kthresh -- sets the lowest decibel level that will be allowed through.
Normally -90 or less, but if higher the threshold will begin removing
low-level signal energy such as background noise.

kloknee, khiknee -- decibel break-points denoting where compression or
expansion will begin. These set the boundaries of a soft-knee curve
joining the low-amplitude 1:1 line and the higher-amplitude compression
ratio line. Typical values are -52 and -30 db. If the two breakpoints
are equal, a hard-knee (angled) map will result.

kratio -- ratio of compression when the signal level is above the knee.
The value 2 will advance the output just one decibel for every input
gain of two; 3 will advance just one in three; 20 just one in twenty,
etc. Inverse ratios will cause signal expansion: .5 gives two for one,
.25 four for one, etc. The value 1 will result in no change.

The actions of compress2 will depend on the parameter settings given. A
hard-knee compressor-limiter, for instance, is obtained from a near-zero
attack time, equal-value break-points, and a very high ratio (say 100).
A noise-gate plus expander is obtained from some positive threshold, and
a fractional ratio above the knee. A voice-activated music compressor
(ducker) will result from feeding the music into aasig and the speech
into acsig. A voice de-esser will result from feeding the voice into
both, with the acsig version being preceded by a band-pass filter that
emphasizes the sibilants. Each application will require some
experimentation to find the best parameter settings; these have been
made k-variable to make this practical.


===========================================================================
connect                                                             *connect*

  Description

The connect opcode, valid only in the orchestra header, sends the
signals from the indicated outlet in all instances of the indicated
source instrument to the indicated inlet in all instances of the
indicated sink instrument. Each inlet instance receives the sum of the
signals in all outlet instances. Thus multiple instances of an outlet
may fan in to one instance of an inlet, or one instance of an outlet may
fan out to multiple instances of an inlet.

When Csound creates a new instance of an instrument template, new
instances of its connections also are created.

  Syntax

connect Tsource1, Soutlet1, Tsink1, Sinlet1

  Initialization

Tsource1 -- String name of the source instrument definition.

Soutlet1 -- String name of the source outlet in the source instrument.

Tsink1 -- String name of the sink instrument definition.

Sinlet1 -- String name of the sink inlet in the sink instrument.


===========================================================================
control                                                             *control*

  Description

Configurable slider controls for realtime user input. Requires Winsound
or TCL/TK. control reads a slider's value.

  Syntax

kres control knum

  Performance

Note that this opcode is not available on Windows due to the
implimentation of pipes on that system

knum -- number of the slider to be read.

Calling control will create a new slider on the screen. There is no
theoretical limit to the number of sliders. Windows and TCL/TK use only
integers for slider values, so the values may need rescaling. GUIs
usually pass values at a fairly slow rate, so it may be advisable to
pass the output of control through port.


===========================================================================
convle                                                               *convle*

  Description

Same as the convolve opcode.

===========================================================================
convolve                                                           *convolve*

  Description

Output is the convolution of signal ain and the impulse response
contained in ifilcod. If more than one output signal is supplied, each
will be convolved with the same impulse response. Note that it is
considerably more efficient to use one instance of the operator when
processing a mono input to create stereo, or quad, outputs.

Note: this opcode can also be written as convle.

  Syntax

ar1 [, ar2] [, ar3] [, ar4] convolve ain, ifilcod [, ichannel]

  Initialization

ifilcod -- integer or character-string denoting an impulse response data
file. An integer denotes the suffix of a file convolve.m; a character
string (in double quotes) gives a filename, optionally a full pathname.
If not a fullpath, the file is sought first in the current directory,
then in the one given by the environment variable SADIR (if defined).
The data file contains the Fourier transform of an impulse response.
Memory usage depends on the size of the data file, which is read and
held entirely in memory during computation, but which is shared by
multiple calls.

ichannel (optional) -- which channel to use from the impulse response
data file.

  Performance

ain -- input audio signal.

convolve implements Fast Convolution. The output of this operator is
delayed with respect to the input. The following formulas should be used
to calculate the delay:

  For (1/kr) <= IRdur:
          Delay = ceil(IRdur * kr) / kr
  For (1/kr) > IRdur: 
          Delay = IRdur * ceil(1/(kr*IRdur))
  Where:
          kr  = Csound control rate
          IRdur = duration, in seconds, of impulse response
          ceil(n) = smallest integer not smaller than n

One should be careful to also take into account the initial delay, if
any, of the impulse response. For example, if an impulse response is
created from a recording, the soundfile may not have the initial delay
included. Thus, one should either ensure that the soundfile has the
correct amount of zero padding at the start, or, preferably, compensate
for this delay in the orchestra (the latter method is more efficient).
To compensate for the delay in the orchestra, subtract the initial delay
from the result calculated using the above formula(s), when calculating
the required delay to introduce into the 'dry' audio path.

For typical applications, such as reverb, the delay will be in the order
of 0.5 to 1.5 seconds, or even longer. This renders the current
implementation unsuitable for real time applications. It could
conceivably be used for real time filtering however, if the number of
taps is small enough.

The author intends to create a higher-level operator at some stage, that
would mix the wet & dry signals, using the correct amount of delay
automatically.


===========================================================================
copya2ftab                                                       *copya2ftab*

  Description

The copya2ftab opcode takes a k-array and copies the contents to an
f-table.

  Syntax

copya2ftab kftbl, tab

  Performance

kftbl -- one-dimensional array for source.

tab -- f-table for destination.


===========================================================================
copyf2array                                                     *copyf2array*

  Description

The copyf2array opcode takes an f-table and copies the contents to a t-var.

  Syntax

copyf2array tab, kftbl

  Performance

tab -- tables for destination.

kftbl -- f-tables for source.


===========================================================================
cos                                                                     *cos*

  Description

Returns the cosine of x (x in radians).

  Syntax

cos(x) (no rate restriction)


===========================================================================
cosseg                                                               *cosseg*

  Description

Trace a series of line segments between specified points with cosine
interpolation.

  Syntax

ares cosseg ia, idur1, ib [, idur2] [, ic] [...]

kres cosseg ia, idur1, ib [, idur2] [, ic] [...]

  Initialization

ia -- starting value.

ib, ic, etc. -- value after dur1 seconds, etc.

idur1 -- duration in seconds of first segment. A zero or negative value
will cause all initialization to be skipped.

idur2, idur3, etc. -- duration in seconds of subsequent segments. A zero
or negative value will terminate the initialization process with the
preceding point, permitting the last-defined line or curve to be
continued indefinitely in performance. The default is zero.

  Performance

These units generate control or audio signals whose values can pass
through 2 or more specified points. The sum of dur values may or may not
equal the instrument's performance time: a shorter performance will
truncate the specified pattern, while a longer one will cause the last
value to be repeated until the end of the note.


===========================================================================
cossegb                                                             *cossegb*

  Description

Trace a series of line segments between specified absolute points with
cosine interpolation.

  Syntax

ares cossegb ia, itim1, ib [, itim2] [, ic] [...]

kres cossegb ia, itim1, ib [, itim2] [, ic] [...]

  Initialization

ia -- starting value.

ib, ic, etc. -- value at tim1 seconds, etc.

itim1 -- time in seconds of end of first segment. A zero or negative
value will cause all initialization to be skipped.

itim2, itim3, etc. -- time in seconds at the end of subsequent segments.

  Performance

These units generate control or audio signals whose values can pass
through 2 or more specified points. The last tim value may or may not
equal the instrument's performance time: a shorter performance will
truncate the specified pattern, while a longer one will cause the last
value to be repeated until the end of the note.


===========================================================================
cossegr                                                             *cossegr*

  Description

Trace a series of line segments between specified points with cosine
interpolation, including a release segment.

  Syntax

ares cossegr ia, idur1, ib [, idur2] [, ic] [...], irel, iz

kres cossegr ia, idur1, ib [, idur2] [, ic] [...], irel, iz

  Initialization

ia -- starting value.

ib, ic, etc. -- value after dur1 seconds, etc.

idur1 -- duration in seconds of first segment. A zero or negative value
will cause all initialization to be skipped.

idur2, idur3, etc. -- duration in seconds of subsequent segments. A zero
or negative value will terminate the initialization process with the
preceding point, permitting the last-defined line or curve to be
continued indefinitely in performance. The default is zero.

irel, iz -- duration in seconds and final value of a note releasing
segment.

  Performance

These units generate control or audio signals whose values can pass
through 2 or more specified points. The sum of dur values may or may not
equal the instrument's performance time: a shorter performance will
truncate the specified pattern, while a longer one will cause the
last-defined segment to continue on in the same direction.

cossegr is amongst the Csound “r” units that contain a note-off sensor
and release time extender. When each senses an event termination or MIDI
noteoff, it immediately extends the performance time of the current
instrument by irel seconds, and sets out to reach the value iz by the
end of that period (no matter which segment the unit is in). “r” units
can also be modified by MIDI noteoff velocities. For two or more
extenders in an instrument, extension is by the greatest period.

You can use other pre-made envelopes which start a release segment upon
receiving a note off message, like linenr and expsegr, or you can
construct more complex envelopes using xtratim and release. Note that
you don't need to use xtratim if you are using cossegr, since the time
is extended automatically.


===========================================================================
cosh                                                                   *cosh*

  Description

Returns the hyperbolic cosine of x (x in radians).

  Syntax

cosh(x) (no rate restriction)


===========================================================================
cosinv                                                               *cosinv*

  Description

Returns the arccosine of x (x in radians).

  Syntax

cosinv(x) (no rate restriction)


===========================================================================
cps2pch                                                             *cps2pch*

  Description

Converts a pitch-class value into cycles-per-second (Hz) for equal
divisions of the octave.

  Syntax

icps cps2pch ipch, iequal

  Initialization

ipch -- Input number of the form 8ve.pc, indicating an 'octave' and
which note in the octave.

iequal -- If positive, the number of equal intervals into which the
'octave' is divided. Must be less than or equal to 100. If negative, is
the number of a table of frequency multipliers.

  Note

 1. The following are essentially the same

    ia  =  cpspch(8.02)
    ib     cps2pch  8.02, 12
    ic     cpsxpch  8.02, 12, 2, 1.02197503906

 2. These are opcodes not functions

 3. Negative values of ipch are allowed.


===========================================================================
cpsmidi                                                             *cpsmidi*

  Description

Get the note number of the current MIDI event, expressed in
cycles-per-second.

  Syntax

icps cpsmidi

  Performance

Get the note number of the current MIDI event, expressed in
cycles-per-second units, for local processing.

  cpsmidi vs. cpsmidinn

The cpsmidi opcode only produces meaningful results in a Midi-activated
note (either real-time or from a Midi score with the -F flag). With
cpsmidi, the Midi note number value is taken from the Midi event that is
internally associated with the instrument instance. On the other hand,
the cpsmidinn opcode may be used in any Csound instrument instance
whether it is activated from a Midi event, score event, line event, or
from another instrument. The input value for cpsmidinn might for example
come from a p-field in a textual score or it may have been retrieved
from the real-time Midi event that activated the current note using the
notnum opcode.


===========================================================================
cpsmidib                                                           *cpsmidib*

  Description

Get the note number of the current MIDI event and modify it by the
current pitch-bend value, express it in cycles-per-second.

  Syntax

icps cpsmidib [irange]

kcps cpsmidib [irange]

  Initialization

irange (optional) -- the pitch bend range in semitones.

  Performance

Get the note number of the current MIDI event, modify it by the current
pitch-bend value, and express the result in cycles-per-second units.
Available as an i-time value or as a continuous k-rate value.


===========================================================================
cpsmidinn                                                         *cpsmidinn*

  Description

Converts a Midi note number value to cycles-per-second.

  Syntax

cpsmidinn (MidiNoteNumber)  (init- or control-rate args only)

where the argument within the parentheses may be a further expression.

  Performance

cpsmidinn is a function that takes an i-rate or k-rate value
representing a Midi note number and returns the equivalent frequency
value in cycles-per-second (Hertz). This conversion assumes that Middle
C is Midi note number 60 and that Middle A is tuned to 440 Hz. Midi note
number values are typically integers in the range from 0 to 127 but
fractional values or values outside of this range will be interpreted
consistently.

  cpsmidinn vs. cpsmidi

The cpsmidinn opcode may be used in any Csound instrument instance
whether it is activated from a Midi event, score event, line event, or
from another instrument. The input value for cpsmidinn might for example
come from a p-field in a textual score or it may have been retrieved
from the real-time Midi event that activated the current note using the
notnum opcode. You must specify an i-rate or k-rate expression for the
Midi note number that is to be converted. On the other hand, the cpsmidi
opcode only produces meaningful results in a Midi-activated note (either
real-time or from a Midi score with the -F flag). With cpsmidi, the Midi
note number value is taken from the Midi event associated with the
instrument instance, and no location or expression for this value may be
specified.

cpsmidinn and its related opcodes are really value converters with a
special function of manipulating pitch data.

Data concerning pitch and frequency can exist in any of the following
forms:

Table 6. Pitch and Frequency Values

Name    Abbreviation
octave point pitch-class (8ve.pc)       pch
octave point decimal    oct
cycles per second       cps
Midi note number (0-127)        midinn

The first two forms consist of a whole number, representing octave
registration, followed by a specially interpreted fractional part. For
pch, the fraction is read as two decimal digits representing the 12
equal-tempered pitch classes from .00 for C to .11 for B. For oct, the
fraction is interpreted as a true decimal fractional part of an octave.
The two fractional forms are thus related by the factor 100/12. In both
forms, the fraction is preceded by a whole number octave index such that
8.00 represents Middle C, 9.00 the C above, etc. Midi note number values
range between 0 and 127 (inclusively) with 60 representing Middle C, and
are usually whole numbers. Thus A440 can be represented alternatively by
440 (cps), 69 (midinn), 8.09 (pch), or 8.75 (oct). Microtonal divisions
of the pch semitone can be encoded by using more than two decimal places.

The mnemonics of the pitch conversion units are derived from morphemes
of the forms involved, the second morpheme describing the source and the
first morpheme the object (result). Thus cpspch(8.09) will convert the
pitch argument 8.09 to its cps (or Hertz) equivalent, giving the value
of 440. Since the argument is constant over the duration of the note,
this conversion will take place at i-time, before any samples for the
current note are produced.

By contrast, the conversion cpsoct(8.75 + k1) which gives the value of
A440 transposed by the octave interval k1. The calculation will be
repeated every k-period since that is the rate at which k1 varies.

  Note

The conversion from pch, oct, or midinn into cps is not a linear
operation but involves an exponential process that could be
time-consuming when executed repeatedly. Csound now uses a built-in
table lookup to do this efficiently, even at audio rates. Because the
table index is truncated without interpolation, pitch resolution when
using one of these opcodes is limited to 8192 discrete and equal
divisions of the octave, and some pitches of the standard 12-tone
equally-tempered scale are very slightly mistuned (by at most 0.15 cents).


===========================================================================
cpsoct                                                               *cpsoct*

  Description

Converts an octave-point-decimal value to cycles-per-second.

  Syntax

cpsoct (oct)  (no rate restriction)

where the argument within the parentheses may be a further expression.

  Performance

cpsoct and its related opcodes are really value converters with a
special function of manipulating pitch data.

Data concerning pitch and frequency can exist in any of the following
forms:

Table 7. Pitch and Frequency Values

Name    Abbreviation
octave point pitch-class (8ve.pc)       pch
octave point decimal    oct
cycles per second       cps
Midi note number (0-127)        midinn

The first two forms consist of a whole number, representing octave
registration, followed by a specially interpreted fractional part. For
pch, the fraction is read as two decimal digits representing the 12
equal-tempered pitch classes from .00 for C to .11 for B. For oct, the
fraction is interpreted as a true decimal fractional part of an octave.
The two fractional forms are thus related by the factor 100/12. In both
forms, the fraction is preceded by a whole number octave index such that
8.00 represents Middle C, 9.00 the C above, etc. Midi note number values
range between 0 and 127 (inclusively) with 60 representing Middle C, and
are usually whole numbers. Thus A440 can be represented alternatively by
440 (cps), 69 (midinn), 8.09 (pch), or 8.75 (oct). Microtonal divisions
of the pch semitone can be encoded by using more than two decimal places.

The mnemonics of the pitch conversion units are derived from morphemes
of the forms involved, the second morpheme describing the source and the
first morpheme the object (result). Thus cpspch(8.09) will convert the
pitch argument 8.09 to its cps (or Hertz) equivalent, giving the value
of 440. Since the argument is constant over the duration of the note,
this conversion will take place at i-time, before any samples for the
current note are produced.

By contrast, the conversion cpsoct(8.75 + k1) which gives the value of
A440 transposed by the octave interval k1. The calculation will be
repeated every k-period since that is the rate at which k1 varies.

  Note

The conversion from pch, oct, or midinn into cps is not a linear
operation but involves an exponential process that could be
time-consuming when executed repeatedly. Csound now uses a built-in
table lookup to do this efficiently, even at audio rates. Because the
table index is truncated without interpolation, pitch resolution when
using one of these opcodes is limited to 8192 discrete and equal
divisions of the octave, and some pitches of the standard 12-tone
equally-tempered scale are very slightly mistuned (by at most 0.15 cents).


===========================================================================
cpspch                                                               *cpspch*

  Description

Converts a pitch-class value to cycles-per-second.

  Syntax

cpspch (pch)  (init- or control-rate args only)

where the argument within the parentheses may be a further expression.

  Performance

cpspch and its related opcodes are really value converters with a
special function of manipulating pitch data.

Data concerning pitch and frequency can exist in any of the following
forms:

Table 8. Pitch and Frequency Values

Name    Abbreviation
octave point pitch-class (8ve.pc)       pch
octave point decimal    oct
cycles per second       cps
Midi note number (0-127)        midinn

The first two forms consist of a whole number, representing octave
registration, followed by a specially interpreted fractional part. For
pch, the fraction is read as two decimal digits representing the 12
equal-tempered pitch classes from .00 for C to .11 for B. For oct, the
fraction is interpreted as a true decimal fractional part of an octave.
The two fractional forms are thus related by the factor 100/12. In both
forms, the fraction is preceded by a whole number octave index such that
8.00 represents Middle C, 9.00 the C above, etc. Midi note number values
range between 0 and 127 (inclusively) with 60 representing Middle C, and
are usually whole numbers. Thus A440 can be represented alternatively by
440 (cps), 69 (midinn), 8.09 (pch), or 8.75 (oct). Microtonal divisions
of the pch semitone can be encoded by using more than two decimal places.

The mnemonics of the pitch conversion units are derived from morphemes
of the forms involved, the second morpheme describing the source and the
first morpheme the object (result). Thus cpspch(8.09) will convert the
pitch argument 8.09 to its cps (or Hertz) equivalent, giving the value
of 440. Since the argument is constant over the duration of the note,
this conversion will take place at i-time, before any samples for the
current note are produced.

By contrast, the conversion cpsoct(8.75 + k1) which gives the value of
A440 transposed by the octave interval k1. The calculation will be
repeated every k-period since that is the rate at which k1 varies.

  Note

The conversion from pch, oct, or midinn into cps is not a linear
operation but involves an exponential process that could be
time-consuming when executed repeatedly. Csound now uses a built-in
table lookup to do this efficiently, even at audio rates. Because the
table index is truncated without interpolation, pitch resolution when
using one of these opcodes is limited to 8192 discrete and equal
divisions of the octave, and some pitches of the standard 12-tone
equally-tempered scale are very slightly mistuned (by at most 0.15 cents).

If you need more precision in the calculation, use cps2pch or cpsxpch
instead.


===========================================================================
cpstmid                                                             *cpstmid*

  Description

This unit is similar to cpsmidi, but allows fully customized
micro-tuning scales.

  Syntax

icps cpstmid ifn

  Initialization

ifn -- function table containing the parameters (numgrades, interval,
basefreq, basekeymidi) and the tuning ratios.

  Performance

Init-rate only

cpsmid requires five parameters, the first, ifn, is the function table
number of the tuning ratios, and the other parameters must be stored in
the function table itself. The function table ifn should be generated by
GEN02, with normalization inhibited. The first four values stored in
this function are:

 1. numgrades -- the number of grades of the micro-tuning scale

 2. interval -- the frequency range covered before repeating the grade
    ratios, for example 2 for one octave, 1.5 for a fifth etc.

 3. basefreq -- the base frequency of the scale in Hz

 4. basekeymidi -- the MIDI note number to which basefreq is assigned
    unmodified

After these four values, the user can begin to insert the tuning ratios.
For example, for a standard 12 note scale with the base frequency of 261
Hz assigned to the key number 60, the corresponding f-statement in the
score to generate the table should be:

  ;          numgrades interval  basefreq basekeymidi tuning ratios (equal temp)   
  f1 0 64 -2   12       2        261        60         1  1.059463094359  1.122462048309  1.189207115003 ..etc...  

Another example with a 24 note scale with a base frequency of 440
assigned to the key number 48, and a repetition interval of 1.5:

  ;           numgrades interval  basefreq basekeymidi tuning-ratios (equal temp)   
  f1 0 64 -2   24        1.5      440        48         1   1.01  1.02  1.03   ..etc...  


===========================================================================
cpstun                                                               *cpstun*

  Description

Returns micro-tuning values at k-rate.

  Syntax

kcps cpstun ktrig, kindex, kfn

  Performance

kcps -- Return value in cycles per second.

ktrig -- A trigger signal used to trigger the evaluation.

kindex -- An integer number denoting an index of scale.

kfn -- Function table containing the parameters (numgrades, interval,
basefreq, basekeymidi) and the tuning ratios.

These opcodes are similar to cpstmid, but work without necessity of MIDI.

cpstun works at k-rate. It allows fully customized micro-tuning scales.
It requires a function table number containing the tuning ratios, and
some other parameters stored in the function table itself.

kindex arguments should be filled with integer numbers expressing the
grade of given scale to be converted in cps. In cpstun, a new value is
evaluated only when ktrig contains a non-zero value. The function table
kfn should be generated by GEN02 and the first four values stored in
this function are parameters that express:

  * numgrades -- The number of grades of the micro-tuning scale.

  * interval -- The frequency range covered before repeating the grade
    ratios, for example 2 for one octave, 1.5 for a fifth etcetera.

  * basefreq -- The base frequency of the scale in cycles per second.

  * basekey -- The integer index of the scale to which to assign
    basefreq unmodified.

After these four values, the user can begin to insert the tuning ratios.
For example, for a standard 12-grade scale with the base-frequency of
261 cps assigned to the key-number 60, the corresponding f-statement in
the score to generate the table should be:

;           numgrades    basefreq     tuning-ratios (eq.temp) .......
;                  interval    basekey
f1 0 64 -2  12     2     261   60     1   1.059463 1.12246 1.18920 ..etc...

Another example with a 24-grade scale with a base frequency of 440
assigned to the key-number 48, and a repetition interval of 1.5:

;                  numgrades       basefreq      tuning-ratios .......
;                          interval       basekey
f1 0 64 -2         24      1.5     440    48     1   1.01  1.02  1.03   ..etc...


===========================================================================
cpstuni                                                             *cpstuni*

  Description

Returns micro-tuning values at init-rate.

  Syntax

icps cpstuni index, ifn

  Initialization

icps -- Return value in cycles per second.

index -- An integer number denoting an index of scale.

ifn -- Function table containing the parameters (numgrades, interval,
basefreq, basekeymidi) and the tuning ratios.

  Performance

These opcodes are similar to cpstmid, but work without necessity of MIDI.

cpstuni works at init-rate. It allows fully customized micro-tuning
scales. It requires a function table number containing the tuning
ratios, and some other parameters stored in the function table itself.

The index argument should be filled with integer numbers expressing the
grade of given scale to be converted in cps. The function table ifn
should be generated by GEN02 and the first four values stored in this
function are parameters that express:

  * numgrades -- The number of grades of the micro-tuning scale.

  * interval -- The frequency range covered before repeating the grade
    ratios, for example 2 for one octave, 1.5 for a fifth etcetera.

  * basefreq -- The base frequency of the scale in cycles per second.

  * basekey -- The integer index of the scale to which to assign
    basefreq unmodified.

After these four values, the user can begin to insert the tuning ratios.
For example, for a standard 12-grade scale with the base-frequency of
261 cps assigned to the key-number 60, the corresponding f-statement in
the score to generate the table should be:

;           numgrades    basefreq     tuning-ratios (eq.temp) .......
;                  interval    basekey
f1 0 64 -2  12     2     261   60     1   1.059463 1.12246 1.18920 ..etc...

Another example with a 24-grade scale with a base frequency of 440
assigned to the key-number 48, and a repetition interval of 1.5:

;                  numgrades       basefreq      tuning-ratios .......
;                          interval       basekey
f1 0 64 -2         24      1.5     440    48     1   1.01  1.02  1.03   ..etc...


===========================================================================
cpsxpch                                                             *cpsxpch*

  Description

Converts a pitch-class value into cycles-per-second (Hz) for equal
divisions of any interval. There is a restriction of no more than 100
equal divisions.

  Syntax

icps cpsxpch ipch, iequal, irepeat, ibase

  Initialization

ipch -- Input number of the form 8ve.pc, indicating an 'octave' and
which note in the octave.

iequal -- if positive, the number of equal intervals into which the
'octave' is divided. Must be less than or equal to 100. If negative, is
the number of a table of frequency multipliers.

irepeat -- Number indicating the interval which is the 'octave.' The
integer 2 corresponds to octave divisions, 3 to a twelfth, 4 is two
octaves, and so on. This need not be an integer, but must be positive.

ibase -- The frequency which corresponds to pitch 0.0

  Note

 1. The following are essentially the same

    ia  =  cpspch(8.02)
    ib     cps2pch  8.02, 12
    ic     cpsxpch  8.02, 12, 2, 1.02197503906

 2. These are opcodes not functions

 3. Negative values of ipch are allowed, but not negative irepeat,
    iequal or ibase.


===========================================================================
cpumeter                                                           *cpumeter*

  Description

Reports the usage of cpu either total or per core to monitor how close
to max-out the processing is.

  Syntax

ktot[,kcpu1, kcpu2,...]cpumeter ifreq

  Initialization

ifreq is the time in seconds that the meter is refreshed. If this is too
low then mainly figures of zero or one hundred occur. A value of 0.1
seems acceptable.

  Performance

cpumeter reads the total idle time in the last ifreq seconds and reports
it as a percentage usage. If more than just ktot results are requested
these report the same value for individual cores.


===========================================================================
cpuprc                                                               *cpuprc*

  Description

Control allocation of cpu resources on a per-instrument basis, to
optimize realtime output.

  Syntax

cpuprc insnum, ipercent

cpuprc Sinsname, ipercent

  Initialization

insnum -- instrument number or string

Sinsname -- instrument number or string

ipercent -- percent of cpu processing-time to assign. Can also be
expressed as a fractional value.

  Performance

cpuprc sets the cpu processing-time percent usage of an instrument, in
order to avoid buffer underrun in realtime performances, enabling a sort
of polyphony theshold. The user must set ipercent value for each
instrument to be activated in realtime. Assuming that the total
theoretical processing time of the cpu of the computer is 100%, this
percent value can only be defined empirically, because there are too
many factors that contribute to limiting realtime polyphony in different
computers.

For example, if ipercent is set to 5% for instrument 1, the maximum
number of voices that can be allocated in realtime, is 20 (5% * 20 =
100%). If the user attempts to play a further note while the 20 previous
notes are still playing, Csound inhibits the allocation of that note and
will display the following warning message:

  can't allocate last note because it exceeds 100% of cpu time

In order to avoid audio buffer underruns, it is suggested to set the
maximum number of voices slightly lower than the real processing power
of the computer. Sometimes an instrument can require more processing
time than normal. If, for example, the instrument contains an oscillator
which reads a table that doesn't fit in cache memory, it will be slower
than normal. In addition, any program running concurrently in
multitasking, can subtract processing power to varying degrees.

At the start, all instruments are set to a default value of ipercent =
0.0% (i.e. zero processing time or rather infinite cpu
processing-speed). This setting is OK for deferred-time sessions.

All instances of cpuprc must be defined in the header section, not in
the instrument body.


===========================================================================
cross2                                                               *cross2*

  Description

This is an implementation of cross synthesis using FFT's.

  Syntax

ares cross2 ain1, ain2, isize, ioverlap, iwin, kbias

  Initialization

isize -- This is the size of the FFT to be performed. The larger the
size the better the frequency response but a sloppy time response.

ioverlap -- This is the overlap factor of the FFT's, must be a power of
two. The best settings are 2 and 4. A big overlap takes a long time to
compile.

iwin -- This is the function table that contains the window to be used
in the analysis. One can use the GEN20 routine to create this window.

  Performance

ain1 -- The stimulus sound. Must have high frequencies for best results.

ain2 -- The modulating sound. Must have a moving frequency response
(like speech) for best results.

kbias -- The amount of cross synthesis. 1 is the normal, 0 is no cross
synthesis.


===========================================================================
crossfm                                                             *crossfm*

  Description

Two oscillators, mutually frequency and/or phase modulated by each other.

  Syntax

a1, a2 crossfm xfrq1, xfrq2, xndx1, xndx2, kcps, ifn1, ifn2 [, iphs1] [, iphs2]

a1, a2 crossfmi xfrq1, xfrq2, xndx1, xndx2, kcps, ifn1, ifn2 [, iphs1] [, iphs2]

a1, a2 crosspm xfrq1, xfrq2, xndx1, xndx2, kcps, ifn1, ifn2 [, iphs1] [, iphs2]

a1, a2 crosspmi xfrq1, xfrq2, xndx1, xndx2, kcps, ifn1, ifn2 [, iphs1] [, iphs2]

a1, a2 crossfmpm xfrq1, xfrq2, xndx1, xndx2, kcps, ifn1, ifn2 [, iphs1] [, iphs2]

a1, a2 crossfmpmi xfrq1, xfrq2, xndx1, xndx2, kcps, ifn1, ifn2 [, iphs1] [, iphs2]

  Initialization

ifn1 -- function table number for oscillator #1. Requires a wrap-around
guard point.

ifn2 -- function table number for oscillator #2. Requires a wrap-around
guard point.

iphs1 (optional, default=0) -- initial phase of waveform in table ifn1,
expressed as a fraction of a cycle (0 to 1). A negative value will cause
phase initialization to be skipped.

iphs2 (optional, default=0) -- initial phase of waveform in table ifn2,
expressed as a fraction of a cycle (0 to 1). A negative value will cause
phase initialization to be skipped.

  Performance

xfrq1 -- a factor that, when multipled by the kcps parameter, gives the
frequency of oscillator #1.

xfrq2 -- a factor that, when multipled by the kcps parameter, gives the
frequency of oscillator #2.

xndx1 -- the index of the modulation of oscillator #2 by oscillator #1.

xndx2 -- the index of the modulation of oscillator #1 by oscillator #2.

kcps -- a common denominator, in cycles per second, for both oscillators
frequencies.

crossfm implements a crossed frequency modulation algorithm. The
audio-rate output of oscillator #1 is used to modulate the frequency
input of oscillator #2 while the audio-rate output of oscillator #2 is
used to modulate the frequency input of oscillator #1. This double
feedback structure produces a rich set of sounds with some chaotic
behaviour. crossfmi behaves like crossfm except that linear
interpolation is used for table lookup.

crosspm and crosspmi implement cross phase modulation between two
oscillators.

crossfmpm and crossfmpmi implement cross frequency/phase modulation
between two oscillators. Oscillator #1 is frequency-modulated by
oscillator #2 while oscillator #2 is phase-modulated by oscillator #1.

You can read my paper in the Csound Journal for more information.

  Warning

Those opcodes may produce very rich spectra, especially with high
modulation indexes, and in some cases foldover aliases may occur if the
sampling rate is not high enough. Moreover the audio output may vary in
function of the sampling rate, due to the non-linearity of the
algorithm. In Csound, two other opcodes have this characteristic: planet
and chuap.


===========================================================================
crunch                                                               *crunch*

  Description

crunch is a semi-physical model of a crunch sound. It is one of the
PhISEM percussion opcodes. PhISEM (Physically Informed Stochastic Event
Modeling) is an algorithmic approach for simulating collisions of
multiple independent sound producing objects.

  Syntax

ares crunch iamp, idettack [, inum] [, idamp] [, imaxshake]

  Initialization

iamp -- Amplitude of output. Note: As these instruments are stochastic,
this is only a approximation.

idettack -- period of time over which all sound is stopped

inum (optional) -- The number of beads, teeth, bells, timbrels, etc. If
zero, the default value is 7.

idamp (optional) -- the damping factor, as part of this equation:

damping_amount = 0.998 + (idamp * 0.002)

The default damping_amount is 0.99806 which means that the default value
of idamp is 0.03. The maximum damping_amount is 1.0 (no damping). This
means the maximum value for idamp is 1.0.

The recommended range for idamp is usually below 75% of the maximum value.

imaxshake (optional) -- amount of energy to add back into the system.
The value should be in range 0 to 1.


===========================================================================
ctrl14                                                               *ctrl14*

  Description

Allows a floating-point 14-bit MIDI signal scaled with a minimum and a
maximum range.

  Syntax

idest ctrl14 ichan, ictlno1, ictlno2, imin, imax [, ifn]

kdest ctrl14 ichan, ictlno1, ictlno2, kmin, kmax [, ifn]

  Initialization

idest -- output signal

ichan -- MIDI channel number (1-16)

ictln1o -- most-significant byte controller number (0-127)

ictlno2 -- least-significant byte controller number (0-127)

imin -- user-defined minimum floating-point value of output

imax -- user-defined maximum floating-point value of output

ifn (optional) -- table to be read when indexing is required. Table must
be normalized. Output is scaled according to imax and imin val.

  Performance

kdest -- output signal

kmin -- user-defined minimum floating-point value of output

kmax -- user-defined maximum floating-point value of output

ctrl14 (i- and k-rate 14 bit MIDI control) allows a floating-point
14-bit MIDI signal scaled with a minimum and a maximum range. The
minimum and maximum values can be varied at k-rate. It can use optional
interpolated table indexing. It requires two MIDI controllers as input.

ctrl14 differs from midic14 because it can be included in score-oriented
instruments without Csound crashes. It needs the additional parameter
ichan containing the MIDI channel of the controller. MIDI channel is the
same for all the controllers used in a single ctrl14 opcode.


===========================================================================
ctrl21                                                               *ctrl21*

  Description

Allows a floating-point 21-bit MIDI signal scaled with a minimum and a
maximum range.

  Syntax

idest ctrl21 ichan, ictlno1, ictlno2, ictlno3, imin, imax [, ifn]

kdest ctrl21 ichan, ictlno1, ictlno2, ictlno3, kmin, kmax [, ifn]

  Initialization

idest -- output signal

ichan -- MIDI channel number (1-16)

ictlno1 -- most-significant byte controller number (0-127)

ictlno2 -- mid-significant byte controller number (0-127)

ictlno3 -- least-significant byte controller number (0-127)

imin -- user-defined minimum floating-point value of output

imax -- user-defined maximum floating-point value of output

ifn (optional) -- table to be read when indexing is required. Table must
be normalized. Output is scaled according to imax and imin val.

  Performance

kdest -- output signal

kmin -- user-defined minimum floating-point value of output

kmax -- user-defined maximum floating-point value of output

ctrl21 (i- and k-rate 21 bit MIDI control) allows a floating-point
21-bit MIDI signal scaled with a minimum and a maximum range. Minimum
and maximum values can be varied at k-rate. It can use optional
interpolated table indexing. It requires three MIDI controllers as input.

ctrl21 differs from midic21 because it can be included in score oriented
instruments without Csound crashes. It needs the additional parameter
ichan containing the MIDI channel of the controller. MIDI channel is the
same for all the controllers used in a single ctrl21 opcode.


===========================================================================
ctrl7                                                                 *ctrl7*

  Description

Allows a floating-point 7-bit MIDI signal scaled with a minimum and a
maximum range.

  Syntax

idest ctrl7 ichan, ictlno, imin, imax [, ifn]

kdest ctrl7 ichan, ictlno, kmin, kmax [, ifn]

adest ctrl7 ichan, ictlno, kmin, kmax [, ifn] [, icutoff]

  Initialization

idest -- output signal

ichan -- MIDI channel (1-16)

ictlno -- MIDI controller number (0-127)

imin -- user-defined minimum floating-point value of output

imax -- user-defined maximum floating-point value of output

ifn (optional) -- table to be read when indexing is required. Table must
be normalized. Output is scaled according to imax and imin val.

icutoff (optional) -- low pass filter cut-off frequency for smoothing
a-rate output.

  Performance

kdest, adest -- output signal

kmin -- user-defined minimum floating-point value of output

kmax -- user-defined maximum floating-point value of output

ctrl7 (i- and k-rate 7 bit MIDI control) allows a floating-point 7-bit
MIDI signal scaled with a minimum and a maximum range. It also allows
optional non-interpolated table indexing. Minimum and maximum values can
be varied at k-rate.

ctrl7 differs from midic7 because it can be included in score-oriented
instruments without Csound crashes. It also needs the additional
parameter ichan containing the MIDI channel of the controller.

The a-rate version of ctrl7 outputs an a-rate variable, which is
low-pass filtered (smoothed). It contains an optional icutoff parameter,
to set the cutoff frecuency for the low-pass filter. The default is 5.


===========================================================================
ctrlinit                                                           *ctrlinit*

  Description

Sets the initial values for a set of MIDI controllers.

  Syntax

ctrlinit ichnl, ictlno1, ival1 [, ictlno2] [, ival2] [, ictlno3] \
      [, ival3] [,...ival32]

  Initialization

ichnl -- MIDI channel number (1-16)

ictlno1, ictlno1, etc. -- MIDI controller numbers (0-127)

ival1, ival2, etc. -- initial value for corresponding MIDI controller
number

  Performance

Sets the initial values for a set of MIDI controllers.


===========================================================================
cuserrnd                                                           *cuserrnd*

  Description

Continuous USER-defined-distribution RaNDom generator.

  Syntax

aout cuserrnd kmin, kmax, ktableNum

iout cuserrnd imin, imax, itableNum

kout cuserrnd kmin, kmax, ktableNum

  Initialization

imin -- minimum range limit

imax -- maximum range limit

itableNum -- number of table containing the random-distribution
function. Such table is generated by the user. See GEN40, GEN41, and
GEN42. The table length does not need to be a power of 2

  Performance

ktableNum -- number of table containing the random-distribution
function. Such table is generated by the user. See GEN40, GEN41, and
GEN42. The table length does not need to be a power of 2

kmin -- minimum range limit

kmax -- maximum range limit

cuserrnd (continuous user-defined-distribution random generator)
generates random values according to a continuous random distribution
created by the user. In this case the shape of the distribution
histogram can be drawn or generated by any GEN routine. The table
containing the shape of such histogram must then be translated to a
distribution function by means of GEN40 (see GEN40 for more details).
Then such function must be assigned to the XtableNum argument of
cuserrnd. The output range can then be rescaled according to the Xmin
and Xmax arguments. cuserrnd linearly interpolates between table
elements, so it is not recommended for discrete distributions (GEN41 and
GEN42).

For a tutorial about random distribution histograms and functions see:

  * D. Lorrain. "A panoply of stochastic cannons". In C. Roads, ed.
    1989. Music machine. Cambridge, Massachusetts: MIT press, pp. 351 -
    379.


===========================================================================
dam                                                                     *dam*

  Description

This opcode dynamically modifies a gain value applied to the input sound
ain by comparing its power level to a given threshold level. The signal
will be compressed/expanded with different factors regarding that it is
over or under the threshold.

  Syntax

ares dam asig, kthreshold, icomp1, icomp2, irtime, iftime

  Initialization

icomp1 -- compression ratio for upper zone.

icomp2 -- compression ratio for lower zone

irtime -- gain rise time in seconds. Time over which the gain factor is
allowed to raise of one unit.

iftime -- gain fall time in seconds. Time over which the gain factor is
allowed to decrease of one unit.

  Performance

asig -- input signal to be modified

kthreshold -- level of input signal which acts as the threshold. Can be
changed at k-time (e.g. for ducking)

Note on the compression factors: A compression ratio of one leaves the
sound unchanged. Setting the ratio to a value smaller than one will
compress the signal (reduce its volume) while setting the ratio to a
value greater than one will expand the signal (augment its volume).


===========================================================================
date                                                                   *date*

  Description

Returns the number seconds since a base date, using the operating
system's clock. The base is 1 January 1970 for Csound using doubles, and
1 January 2010 for versions using floats. On operating systemms with
sufficient resolution the date includes fractional seconds.

  Syntax

ir[, inano] date

kr[, knano] date

  Initialization and Performance

ir -- value at i-time, of the system clock in seconds since the start of
the epoch.

kr -- value at k-time, of the system clock in seconds since the start of
the epoch.

inano -- value at i-time of the nanoseconds since last second tick.

knano -- value at k-time of the nanoseconds since last second tick.

Note that the base date was originally 1970 but since verson 5.14 it has
been changed as single precission floating point numbers are
insufficient to indicate changes.

The optional answer and resolution including fractions of a second
introduced in version 6.07.


===========================================================================
dates                                                                 *dates*

  Description

Returns as a string the date and time specified.

  Syntax

Sir dates [ itime]

  Initialization

itime -- the time is seconds since the start of the epoch. If omited or
negative the current time is taken.

Sir -- the date and time as a string.


===========================================================================
db                                                                       *db*

  Description

Returns the amplitude equivalent for a given decibel amount. This opcode
is the same as ampdb.

  Syntax

db(x)

This function works at a-rate, i-rate, and k-rate.

  Initialization

x -- a value expressed in decibels.

  Performance

Returns the amplitude for a given decibel amount.


===========================================================================
dbamp                                                                 *dbamp*

  Description

Returns the decibel equivalent of the raw amplitude x.

  Syntax

dbamp(x)  (init-rate or control-rate args only)


===========================================================================
dbfsamp                                                             *dbfsamp*

  Description

Returns the decibel equivalent of the raw amplitude x, relative to full
scale amplitude. Full scale is assumed to be 16 bit. New is Csound
version 4.10.

  Syntax

dbfsamp(x)  (init-rate or control-rate args only)


===========================================================================
dcblock                                                             *dcblock*

  Description

Implements the DC blocking filter

Y[i] = X[i] - X[i-1] + (igain * Y[i-1])

Based on work by Perry Cook.

  Syntax

ares dcblock ain [, igain]

  Initialization

igain -- the gain of the filter, which defaults to 0.99

  Performance

ain -- audio signal input

  Note

The new dcblock2 opcode is an improved method of removing DC from an
audio signal.


===========================================================================
dcblock2                                                           *dcblock2*

  Description

Implements a DC blocking filter with improved DC attenuation.

  Syntax

ares dcblock2 ain [, iorder] [, iskip]

  Initialization

iorder -- filter order, minimum 4th order, defaults to 128.

iskip -- set to 1 to skip initialization (defaults to 0).

  Performance

ares -- filered audio signal

ain -- input audio signal

  Note

Using a value for iorder less that ksmps will not reduce DC offset
efficiently.


===========================================================================
dconv                                                                 *dconv*

  Description

A direct convolution opcode.

  Syntax

ares dconv asig, isize, ifn

  Initialization

isize -- the size of the convolution buffer to use. If the buffer size
is smaller than the size of ifn, then only the first isize values will
be used from the table.

ifn -- table number of a stored function containing the impulse response
for convolution.

  Performance

Rather than the analysis/resynthesis method of the convolve opcode,
dconv uses direct convolution to create the result. For small tables it
can do this quite efficiently, however larger table require much more
time to run. dconv does (isize * ksmps) multiplies on every k-cycle.
Therefore, reverb and delay effects are best done with other opcodes
(unless the times are short).

dconv was designed to be used with time varying tables to facilitate new
realtime filtering capabilities.


===========================================================================
delay                                                                 *delay*

  Description

A signal can be read from or written into a delay path, or it can be
automatically delayed by some time interval.

  Syntax

ares delay asig, idlt [, iskip]

  Initialization

idlt -- requested delay time in seconds. This can be as large as
available memory will permit. The space required for n seconds of delay
is 4n * sr bytes. It is allocated at the time the instrument is first
initialized, and returned to the pool at the end of a score section.

iskip (optional, default=0) -- initial disposition of delay-loop data
space (see reson). The default value is 0.

  Performance

asig -- audio signal

delay is a composite of delayr and delayw, both reading from and writing
into its own storage area. It can thus accomplish signal time-shift,
although modified feedback is not possible. There is no minimum delay
period.


===========================================================================
delay1                                                               *delay1*

  Description

Delays an input signal by one sample.

  Syntax

ares delay1 asig [, iskip]

  Initialization

iskip (optional, default=0) -- initial disposition of delay-loop data
space (see reson). The default value is 0.

  Performance

delay1 is a special form of delay that serves to delay the audio signal
asig by just one sample. It is thus functionally equivalent to the delay
opcode but is more efficient in both time and space. This unit is
particularly useful in the fabrication of generalized non-recursive
filters.


===========================================================================
delayk                                                               *delayk*

  Description

k-rate delay opcodes

  Syntax

kr delayk   ksig, idel[, imode]

kr vdel_k   ksig, kdel, imdel[, imode]

  Initialization

idel -- delay time (in seconds) for delayk. It is rounded to the nearest
integer multiple of a k-cycle (i.e. 1/kr).

imode -- sum of 1 for skipping initialization (e.g. in tied notes) and 2
for holding the first input value during the initial delay, instead of
outputting zero. This is mainly of use when delaying envelopes that do
not start at zero.

imdel -- maximum delay time for vdel_k, in seconds.

  Performance

kr -- the output signal. Note: neither of the opcodes interpolate the
output.

ksig -- the input signal.

kdel -- delay time (in seconds) for vdel_k. It is rounded to the nearest
integer multiple of a k-cycle (i.e. 1/kr).


===========================================================================
delayr                                                               *delayr*

  Description

Reads from an automatically established digital delay line.

  Syntax

ares delayr idlt [, iskip]

  Initialization

idlt -- requested delay time in seconds. This can be as large as
available memory will permit. The space required for n seconds of delay
is 4n * sr bytes. It is allocated at the time the instrument is first
initialized, and returned to the pool at the end of a score section.

iskip (optional, default=0) -- initial disposition of delay-loop data
space (see reson). The default value is 0.

  Performance

delayr reads from an automatically established digital delay line, in
which the signal retrieved has been resident for idlt seconds. This unit
must be paired with and precede an accompanying delayw unit. Any other
Csound statements can intervene.


===========================================================================
delayw                                                               *delayw*

  Description

Writes the audio signal to a digital delay line.

  Syntax

delayw asig

  Performance

delayw writes asig into the delay area established by the preceding
delayr unit. Viewed as a pair, these two units permit the formation of
modified feedback loops, etc. However, there is a lower bound on the
value of idlt, which must be at least 1 control period (or 1/kr).


===========================================================================
deltap                                                               *deltap*

  Description

Tap a delay line at variable offset times.

  Syntax

ares deltap kdlt

  Performance

kdlt -- specifies the tapped delay time in seconds. Each can range from
1 control period to the full delay time of the read/write pair; however,
since there is no internal check for adherence to this range, the user
is wholly responsible. Each argument can be a constant, a variable, or a
time-varying signal.

deltap extracts sound by reading the stored samples directly.

This opcode can tap into a delayr/delayw pair, extracting delayed audio
from the idlt seconds of stored sound. There can be any number of deltap
and/or deltapi units between a read/write pair. Each receives an audio
tap with no change of original amplitude.

This opcode can provide multiple delay taps for arbitrary delay path and
feedback networks. They can deliver either constant-time or time-varying
taps, and are useful for building chorus effects, harmonizers, and
Doppler shifts. Constant-time delay taps (and some slowly changing ones)
do not need interpolated readout; they are well served by deltap.
Medium-paced or fast varying dlt's, however, will need the extra
services of deltapi.

delayr/delayw pairs may be interleaved. To associate a delay tap unit
with a specific delayr unit, it not only has to be located between that
delayr and the appropriate delayw unit, but must also precede any
following delayr units. See Example 2. (This feature added in Csound
version 3.57 by Jens Groh and John ffitch).

N.B. k-rate delay times are not internally interpolated, but rather lay
down stepped time-shifts of audio samples; this will be found quite
adequate for slowly changing tap times. For medium to fast-paced
changes, however, one should provide a higher resolution audio-rate
timeshift as input.


===========================================================================
deltap3                                                             *deltap3*

  Description

Taps a delay line at variable offset times, uses cubic interpolation.

  Syntax

ares deltap3 xdlt

  Performance

xdlt -- specifies the tapped delay time in seconds. Each can range from
1 control period to the full delay time of the read/write pair; however,
since there is no internal check for adherence to this range, the user
is wholly responsible. Each argument can be a constant, a variable, or a
time-varying signal; the xdlt argument in deltap3 implies that an
audio-varying delay is permitted there.

deltap3 is experimental, and uses cubic interpolation. (New in Csound
version 3.50.)

This opcode can tap into a delayr/delayw pair, extracting delayed audio
from the idlt seconds of stored sound. There can be any number of deltap
and/or deltapi units between a read/write pair. Each receives an audio
tap with no change of original amplitude.

This opcode can provide multiple delay taps for arbitrary delay path and
feedback networks. They can deliver either constant-time or time-varying
taps, and are useful for building chorus effects, harmonizers, and
Doppler shifts. Constant-time delay taps (and some slowly changing ones)
do not need interpolated readout; they are well served by deltap.
Medium-paced or fast varying dlt's, however, will need the extra
services of deltapi.

delayr/delayw pairs may be interleaved. To associate a delay tap unit
with a specific delayr unit, it not only has to be located between that
delayr and the appropriate delayw unit, but must also precede any
following delayr units. See Example 2. (This feature added in Csound
version 3.57 by Jens Groh and John ffitch).

N.B. k-rate delay times are not internally interpolated, but rather lay
down stepped time-shifts of audio samples; this will be found quite
adequate for slowly changing tap times. For medium to fast-paced
changes, however, one should provide a higher resolution audio-rate
timeshift as input.


===========================================================================
deltapi                                                             *deltapi*

  Description

Taps a delay line at variable offset times, uses interpolation.

  Syntax

ares deltapi xdlt

  Performance

xdlt -- specifies the tapped delay time in seconds. Each can range from
1 control period to the full delay time of the read/write pair; however,
since there is no internal check for adherence to this range, the user
is wholly responsible. Each argument can be a constant, a variable, or a
time-varying signal; the xdlt argument in deltapi implies that an
audio-varying delay is permitted there.

deltapi extracts sound by interpolated readout. By interpolating between
adjacent stored samples deltapi represents a particular delay time with
more accuracy, but it will take about twice as long to run.

This opcode can tap into a delayr/delayw pair, extracting delayed audio
from the idlt seconds of stored sound. There can be any number of deltap
and/or deltapi units between a read/write pair. Each receives an audio
tap with no change of original amplitude.

This opcode can provide multiple delay taps for arbitrary delay path and
feedback networks. They can deliver either constant-time or time-varying
taps, and are useful for building chorus effects, harmonizers, and
Doppler shifts. Constant-time delay taps (and some slowly changing ones)
do not need interpolated readout; they are well served by deltap.
Medium-paced or fast varying dlt's, however, will need the extra
services of deltapi.

delayr/delayw pairs may be interleaved. To associate a delay tap unit
with a specific delayr unit, it not only has to be located between that
delayr and the appropriate delayw unit, but must also precede any
following delayr units. See Example 2. (This feature added in Csound
version 3.57 by Jens Groh and John ffitch).

N.B. k-rate delay times are not internally interpolated, but rather lay
down stepped time-shifts of audio samples; this will be found quite
adequate for slowly changing tap times. For medium to fast-paced
changes, however, one should provide a higher resolution audio-rate
timeshift as input.


===========================================================================
deltapn                                                             *deltapn*

  Description

Tap a delay line at variable offset times.

  Syntax

ares deltapn xnumsamps

  Performance

xnumsamps -- specifies the tapped delay time in number of samples. Each
can range from 1 control period to the full delay time of the read/write
pair; however, since there is no internal check for adherence to this
range, the user is wholly responsible. Each argument can be a constant,
a variable, or a time-varying signal.

deltapn is identical to deltapi, except delay time is specified in
number of samples, instead of seconds (Hans Mikelson).

This opcode can tap into a delayr/delayw pair, extracting delayed audio
from the idlt seconds of stored sound. There can be any number of deltap
and/or deltapi units between a read/write pair. Each receives an audio
tap with no change of original amplitude.

This opcode can provide multiple delay taps for arbitrary delay path and
feedback networks. They can deliver either constant-time or time-varying
taps, and are useful for building chorus effects, harmonizers, and
Doppler shifts. Constant-time delay taps (and some slowly changing ones)
do not need interpolated readout; they are well served by deltap.
Medium-paced or fast varying dlt's, however, will need the extra
services of deltapi.

delayr/delayw pairs may be interleaved. To associate a delay tap unit
with a specific delayr unit, it not only has to be located between that
delayr and the appropriate delayw unit, but must also precede any
following delayr units. See Example 2. (This feature added in Csound
version 3.57 by Jens Groh and John ffitch).

N.B. k-rate delay times are not internally interpolated, but rather lay
down stepped time-shifts of audio samples; this will be found quite
adequate for slowly changing tap times. For medium to fast-paced
changes, however, one should provide a higher resolution audio-rate
timeshift as input.


===========================================================================
deltapx                                                             *deltapx*

  Description

deltapx is similar to deltapi or deltap3. However, it allows higher
quality interpolation. This opcode can read from and write to a
delayr/delayw delay line with interpolation.

  Syntax

aout deltapx adel, iwsize

  Initialization

iwsize -- interpolation window size in samples. Allowed values are
integer multiplies of 4 in the range 4 to 1024. iwsize = 4 uses cubic
interpolation. Increasing iwsize improves sound quality at the expense
of CPU usage, and minimum delay time.

  Performance

aout -- Output signal.

adel -- Delay time in seconds.

a1      delayr   idlr
        deltapxw a2, adl1, iws1
a3      deltapx  adl2, iws2
        deltapxw a4, adl3, iws3
        delayw   a5

Minimum and maximum delay times:

idlr >= 1/kr                                Delay line length
adl1 >= (iws1/2)/sr                         Write before read
adl1 <= idlr - (1 + iws1/2)/sr              (allows shorter delays)
adl2 >= 1/kr + (iws2/2)/sr                  Read time
adl2 <= idlr - (1 + iws2/2)/sr
adl2 >= adl1 + (iws1 + iws2) / (2*sr)
adl2 >= 1/kr + adl3 + (iws2 + iws3) / (2*sr)
adl3 >= (iws3/2)/sr                         Write after read
adl3 <= idlr - (1 + iws3/2)/sr              (allows feedback)

  Note

Window sizes for opcodes other than deltapx are: deltap, deltapn: 1,
deltapi: 2 (linear), deltap3: 4 (cubic)


===========================================================================
deltapxw                                                           *deltapxw*

  Description

deltapxw mixes the input signal to a delay line. This opcode can be
mixed with reading units (deltap, deltapn, deltapi, deltap3, and
deltapx) in any order; the actual delay time is the difference of the
read and write time. This opcode can read from and write to a
delayr/delayw delay line with interpolation.

  Syntax

deltapxw ain, adel, iwsize

  Initialization

iwsize -- interpolation window size in samples. Allowed values are
integer multiplies of 4 in the range 4 to 1024. iwsize = 4 uses cubic
interpolation. Increasing iwsize improves sound quality at the expense
of CPU usage, and minimum delay time.

  Performance

ain -- Input signal.

adel -- Delay time in seconds.

a1      delayr   idlr
        deltapxw a2, adl1, iws1
a3      deltapx  adl2, iws2
        deltapxw a4, adl3, iws3
        delayw   a5

Minimum and maximum delay times:

idlr >= 1/kr                                Delay line length
adl1 >= (iws1/2)/sr                         Write before read
adl1 <= idlr - (1 + iws1/2)/sr              (allows shorter delays)
adl2 >= 1/kr + (iws2/2)/sr                  Read time
adl2 <= idlr - (1 + iws2/2)/sr
adl2 >= adl1 + (iws1 + iws2) / (2*sr)
adl2 >= 1/kr + adl3 + (iws2 + iws3) / (2*sr)
adl3 >= (iws3/2)/sr                         Write after read
adl3 <= idlr - (1 + iws3/2)/sr              (allows feedback)

  Note

Window sizes for opcodes other than deltapx are: deltap, deltapn: 1,
deltapi: 2 (linear), deltap3: 4 (cubic)


===========================================================================
denorm                                                               *denorm*

  Description

Mixes low level (~1e-20 for floats, and ~1e-56 for doubles) noise to a
list of a-rate signals. Can be used before IIR filters and reverbs to
avoid denormalized numbers which may otherwise result in significantly
increased CPU usage.

  Syntax

denorm a1[, a2[, a3[, ... ]]]

  Performance

a1[, a2[, a3[, ... ]]] -- signals to mix noise with

Some processor architectures (particularly Pentium IVs) are very slow at
processing extremely small numbers. These small numbers can appear as a
result of some decaying feedback process like reverb and IIR filters.
Low level noise can be added so that very small numbers are never
reached, and they are 'absorbed' by this 'noise floor'.

If CPU usage goes to 100% at the end of reverb tails, or you get audio
glitches in processes that shouldn't use too much CPU, using denorm
before the culprit opcode or process might solve the problem.


===========================================================================
diff                                                                   *diff*

  Description

Modify a signal by differentiation.

  Syntax

ares diff asig [, iskip]

kres diff ksig [, iskip]

  Initialization

iskip (optional) -- initial disposition of internal save space (see
reson). The default value is 0.

  Performance

integ and diff perform integration and differentiation on an input
control signal or audio signal. Each is the converse of the other, and
applying both will reconstruct the original signal. Since these units
are special cases of low-pass and high-pass filters, they produce a
scaled (and phase shifted) output that is frequency-dependent. Thus diff
of a sine produces a cosine, with amplitude 2 * pi * Hz / sr that of the
original (for each component partial); integ will inversely affect the
magnitudes of its component inputs. With this understanding, these units
can provide useful signal modification.


===========================================================================
directory                                                         *directory*

  Description

Reads a directory for files and passes them to a string array. Users can
set the file type by passing a file extension as a string.

  Syntax

SFiles[] directory SDirectory[, SExtention]

  Initialization

SDirectory -- a string that identifies the directory to browse for files

SExtention -- Optional. Sets the desired file type. If left out, all
files names will be retrieved.

  Performance

SFiles[] -- a string array that holds the names of all files of a given
type found in the directory.

  Note

This works at i-time only and will not pick up changes made to the
directory after performance has started.


===========================================================================
diskgrain                                                         *diskgrain*

  Description

diskgrain implements synchronous granular synthesis. The source sound
for the grains is obtained by reading a soundfile containing the samples
of the source waveform.

  Syntax

asig diskgrain Sfname, kamp, kfreq, kpitch, kgrsize, kprate, \
      ifun, iolaps [,imaxgrsize , ioffset]

  Initialization

Sfilename -- source soundfile.

ifun -- grain envelope function table.

iolaps -- maximum number of overlaps, max(kfreq)*max(kgrsize).
Estimating a large value should not affect performance, but exceeding
this value will probably have disastrous consequences.

imaxgrsize -- max grain size in secs (default 1.0).

ioffset -- start offset in secs from beginning of file (default: 0).

  Performance

kamp -- amplitude scaling

kfreq -- frequency of grain generation, or density, in grains/sec.

kpitch -- grain pitch scaling (1=normal pitch, < 1 lower, > 1 higher;
negative, backwards)

kgrsize -- grain size in secs.

kprate -- readout pointer rate, in grains. The value of 1 will advance
the reading pointer 1 grain ahead in the source table. Larger values
will time-compress and smaller values will time-expand the source
signal. Negative values will cause the pointer to run backwards and zero
will freeze it.

The grain generator has full control of frequency (grains/sec), overall
amplitude, grain pitch (a sampling increment) and grain size (in secs),
both as fixed or time-varying (signal) parameters. An extra parameter is
the grain pointer speed (or rate), which controls which position the
generator will start reading samples in the file for each successive
grain. It is measured in fractions of grain size, so a value of 1 (the
default) will make each successive grain read from where the previous
grain should finish. A value of 0.5 will make the next grain start at
the midway position from the previous grain start and finish, etc.. A
value of 0 will make the generator read always from a fixed position
(wherever the pointer was last at). A negative value will decrement
pointer positions. This control gives extra flexibility for creating
timescale modifications in the resynthesis.

Diskgrain will generate any number of parallel grain streams (which will
depend on grain density/frequency), up to the olaps value (default 100).
The number of streams (overlapped grains) is determined by
grainsize*grain_freq. More grain overlaps will demand more calculations
and the synthesis might not run in realtime (depending on processor power).

Diskgrain can simulate FOF-like formant synthesis, provided that a
suitable shape is used as grain envelope and a sinewave as the grain
wave. For this use, grain sizes of around 0.04 secs can be used. The
formant centre frequency is determined by the grain pitch. Since this is
a sampling increment, in order to use a frequency in Hz, that value has
to be scaled by tablesize/sr. Grain frequency will determine the
fundamental.

This opcode is a variation on the syncgrain opcode.

  Note
diskgrain does not do any resanmpling, so if the sample rate of the
source filename is not the same as csound's sr value there will be pitch
shifts


===========================================================================
diskin                                                               *diskin*

  Description

Reads audio data from an external device or stream and can alter its pitch.

  Syntax

ar1 [, ar2 [, ar3 [, ... arN]]] diskin ifilcod[, kpitch[, iskiptim \
      [, iwraparound[, iformat[, iskipinit]]]]]

Note the N was 24 in versions before 5.14, and 40 after.

ar1[] diskin ifilcod[, kpitch[, iskiptim \
      [, iwraparound[, iformat[, iskipinit]]]]]

(in this version, the number of output channels is not limited.)

  Initialization

ifilcod -- integer or character-string denoting the source soundfile
name. An integer denotes the file soundin.filcod ; a character-string
(in double quotes, spaces permitted) gives the filename itself,
optionally a full pathname. If not a full path, the named file is sought
first in the current directory, then in that given by the environment
variable SSDIR (if defined) then by SFDIR. See also GEN01.

iskptim (optional) -- time in seconds of input sound to be skipped. The
default value is 0.

iformat (optional) -- specifies the audio data file format:

  * 1 = 8-bit signed char (high-order 8 bits of a 16-bit integer)

  * 2 = 8-bit A-law bytes

  * 3 = 8-bit U-law bytes

  * 4 = 16-bit short integers

  * 5 = 32-bit long integers

  * 6 = 32-bit floats

  * 7 = 8-bit unsigned int (not available in Csound versions older than
    5.00)

  * 8 = 24-bit int (not available in Csound versions older than 5.00)

  * 9 = 64-bit doubles (not available in Csound versions older than 5.00)

iwraparound -- 1 = on, 0 = off (wraps around to end of file either
direction, enabling looping)

iskipinit switches off all initialisation if non zero (default =0). This
was introduced in 4_23f13 and csound5.

If iformat = 0 it is taken from the soundfile header, and if no header
from the Csound -o command-line flag. The default value is 0.

  Performance

a1 ... a24 -- output signals, in the range -0dbfs to 0dbfs. Any samples
before the beginning (i.e. negative location) and after the end of the
file are assumed to be zero, unless iwrap is non-zero. The number of
output arguments must be the same as the number of sound file channels -
which can be determined with the filenchnls opcode, otherwise an init
error will occur.

ar1[] --- output signals, in a-rate array of size N, where N is the
number of channels in the file. Arrays are automatically allocated to
the correct size.

kpitch -- can be any real number. A negative number signifies backwards
playback. The given number is a pitch ratio, where:

  * 1 = normal pitch (default)

  * 2 = 1 octave higher

  * 3 = 12th higher, etc.

  * .5 = 1 octave lower

  * .25 = 2 octaves lower, etc.

  * -1 = normal pitch backwards

  * -2 = 1 octave higher backwards, etc.

[Caution]       Note to Windows users

Windows users typically use back-slashes, “\”, when specifying the paths
of their files. As an example, a Windows user might use the path
“c:\music\samples\loop001.wav”. This is problematic because back-slashes
are normally used to specify special characters.

To correctly specify this path in Csound, one may alternately:

  * Use forward slashes: c:/music/samples/loop001.wav

  * Use back-slash special characters, “\\”: c:\\music\\samples\\loop001.wav


===========================================================================
diskin2                                                             *diskin2*

  Description

Reads audio data from a file, and can alter its pitch using one of
several available interpolation types, as well as convert the sample
rate to match the orchestra sr setting. diskin2 can also read
multichannel files with any number of channels in the range 1 to 24 in
versions before 5.14, and 40 after.

  Syntax

a1[, a2[, ... aN]] diskin2 ifilcod[, kpitch[, iskiptim \
      [, iwrap[, iformat[, iwsize[, ibufsize[, iskipinit]]]]]]]

ar1[] diskin2 ifilcod[, kpitch[, iskiptim \
      [, iwrap[, iformat[, iwsize[, ibufsize[, iskipinit]]]]]]]

(in the array output version, the number of output channels does not
have an upper limit.)

  Initialization

ifilcod -- integer or character-string denoting the source soundfile
name. An integer denotes the file soundin.ifilcod; a character-string
(in double quotes, spaces permitted) gives the filename itself,
optionally a full pathname. If not a full path, the named file is sought
first in the current directory, then in those given by the environment
variable SSDIR (if defined) then by SFDIR. See also GEN01. Note: files
longer than 2^31 -1 sample frames may not be played correctly on 32-bit
platforms; this means a maximum length about 3 hours with a sample rate
of 192000 Hz.

iskiptim (optional, defaults to zero) -- time in seconds of input sound
to be skipped, assuming kpitch=1. Can be negative, to add
-iskiptim/kpitch seconds of delay instead of skipping sound.

  Note

If iwrap is not 0 (locations are wrapped), iskiptim will not delay the
sound if a negative value is used. Instead, the negative value will be
"wrapped" from the end of the file.

iwrap (optional, defaults to zero) -- if set to any non-zero value, read
locations that are negative or are beyond the end of the file are
wrapped to the duration of the sound file instead of assuming zero
samples. Useful for playing a file in a loop.

  Note

If iwrap is enabled, the file length should not be shorter than the
interpolation window size (see below), otherwise there may be clicks in
the sound output.

iformat (optional, defaults to zero) -- sample format, for raw
(headerless) files only. This parameter is ignored if the file has a
header. Allowed values are:

  * 0: 16-bit short integers

  * 1: 8-bit signed char (high-order 8 bits of a 16-bit integer)

  * 2: 8-bit A-law bytes

  * 3: 8-bit U-law bytes

  * 4: 16-bit short integers

  * 5: 32-bit long integers

  * 6: 32-bit floats

  * 7: 8-bit unsigned int

  * 8: 24-bit int

  * 9: 64-bit doubles

iwsize (optional, defaults to zero) -- interpolation window size, in
samples. Can be one of the following:

  * 1: round to nearest sample (no interpolation, for kpitch=1)

  * 2: linear interpolation

  * 4: cubic interpolation

  * >= 8: iwsize point sinc interpolation with anti-aliasing (slow)

Zero or negative values select the default, which is cubic interpolation.

  Note

If interpolation is used, kpitch is automatically scaled by the ratio of
the sample rate of the sound file and the orchestra, so that the file
will always be played at the original pitch if kpitch is 1. However, the
sample rate conversion is disabled if iwsize is 1.

ibufsize (optional, defaults to 0) -- buffer size in mono samples (not
sample frames). This is only the suggested value, the actual setting
will be rounded so that the number of sample frames is an integer power
of two and is in the range 128 (or iwsize if greater than 128) to
1048576. The default, which is 4096, and is enabled by zero or negative
values, should be suitable for most uses, but for non-realtime mixing of
many large sound files, a high buffer setting is recommended to improve
the efficiency of disk reads. For real time audio output, reading the
files from a fast RAM file system (on platforms where this option is
available) with a small buffer size may be preferred.

iskipinit (optional, defaults to 0) -- skip initialization if set to any
non-zero value.

  Performance

a1 ... a24 -- output signals, in the range -0dbfs to 0dbfs. Any samples
before the beginning (i.e. negative location) and after the end of the
file are assumed to be zero, unless iwrap is non-zero. The number of
output arguments must be the same as the number of sound file channels -
which can be determined with the filenchnls opcode, otherwise an init
error will occur.

ar1[] --- output signals, in a-rate array of size N, where N is the
number of channels in the file. Arrays are automatically allocated to
the correct size.

  Note

It is more efficient to read a single file with many channels, than many
files with only a single channel, especially with high iwsize settings.

kpitch -- transpose the pitch of input sound by this factor (e.g. 0.5
means one octave lower, 2 is one octave higher, and 1 is the original
pitch, which is the default value). Fractional and negative values are
allowed (the latter results in playing the file backwards, however, in
this case the skip time parameter should be set to some positive value,
e.g. the length of the file, or iwrap should be non-zero, otherwise
nothing would be played). If interpolation is enabled, and the sample
rate of the file differs from the orchestra sample rate, the transpose
ratio is automatically adjusted to make sure that kpitch=1 plays at the
original pitch. Using a high iwsize setting (40 or more) can
significantly improve sound quality when transposing up, although at the
expense of high CPU usage.


===========================================================================
dispfft                                                             *dispfft*

  Description

These units will print orchestra init-values, or produce graphic display
of orchestra control signals and audio signals. Uses X11 windows if
enabled, else (or if -g flag is set) displays are approximated in ASCII
characters.

  Syntax

dispfft xsig, iprd, iwsiz [, iwtyp] [, idbout] [, iwtflg] [,imin] [,imax]

  Initialization

iprd -- the period of display in seconds.

iwsiz -- size of the input window in samples. A window of iwsiz points
will produce a Fourier transform of iwsiz/2 points, spread linearly in
frequency from 0 to sr/2. iwsiz must be a power of 2, with a minimum of
16 and a maximum of 4096. The windows are permitted to overlap.

iwtyp (optional, default=0) -- window type. 0 = rectangular, 1 =
Hanning. The default value is 0 (rectangular).

idbout (optional, default=0) -- units of output for the Fourier
coefficients. 0 = magnitude, 1 = decibels. The default is 0 (magnitude).

iwtflg (optional, default=0) -- wait flag. If non-zero, each display is
held until released by the user. The default value is 0 (no wait).

imin (optional, default=0) -- minimum FFT bin used in display.

imax (optional, default=winsize/2) -- maximum FFT bin to be used in
display.

  Performance

dispfft -- displays the Fourier Transform of an audio or control signal
(asig or ksig) every iprd seconds using the Fast Fourier Transform method.


===========================================================================
display                                                             *display*

  Description

These units will print orchestra init-values, or produce graphic display
of orchestra control signals and audio signals. Uses X11 windows if
enabled, else (or if -g flag is set) displays are approximated in ASCII
characters.

  Syntax

display xsig, iprd [, inprds] [, iwtflg]

  Initialization

iprd -- the period of display in seconds.

inprds (optional, default=1) -- Number of display periods retained in
each display graph. A value of 2 or more will provide a larger
perspective of the signal motion. The default value is 1 (each graph
completely new). inprds is a scaling factor for the displayed waveform,
controlling how many iprd-sized frames of samples are drawn in the
window (the default and minimum value is 1.0). Higher inprds values are
slower to draw (more points to draw) but will show the waveform
scrolling through the window, which is useful with low iprd values.

iwtflg (optional, default=0) -- wait flag. If non-zero, each display is
held until released by the user. The default value is 0 (no wait).

  Performance

display -- displays the audio or control signal xsig every iprd seconds,
as an amplitude vs. time graph.


===========================================================================
distort                                                             *distort*

  Description

Distort an audio signal via waveshaping and optional clipping.

  Syntax

ar distort asig, kdist, ifn[, ihp, istor]

  Initialization

ifn -- table number of a waveshaping function with extended guard point.
The function can be of any shape, but it should pass through 0 with
positive slope at the table mid-point. The table size need not be large,
since it is read with interpolation.

ihp -- (optional) half-power point (in cps) of an internal low-pass
filter. The default value is 10.

istor -- (optional) initial disposition of internal data space (see
reson). The default value is 0.

  Performance

asig -- Audio signal to be processed

kdist -- Amount of distortion (usually between 0 and 1)

This unit distorts an incoming signal using a waveshaping function ifn
and a distortion index kdist. The input signal is first compressed using
a running rms, then passed through a waveshaping function which may
modify its shape and spectrum. Finally it is rescaled to approximately
its original power.

The amount of distortion depends on the nature of the shaping function
and on the value of kdist, which generally ranges from 0 to 1. For low
values of kdist, we should like the shaping function to pass the signal
almost unchanged. This will be the case if, at the mid-point of the
table, the shaping function is near-linear and is passing through 0 with
positive slope. A line function from -1 to +1 will satisfy this
requirement; so too will a sigmoid (sinusoid from 270 to 90 degrees). As
kdist is increased, the compressed signal is expanded to encounter more
and more of the shaping function, and if this becomes non-linear the
signal is increasingly bent on read-through to cause distortion.

When kdist becomes large enough, the read-through process will
eventually hit the outer limits of the table. The table is not read with
wrap-around, but will “stick” at the end-points as the incoming signal
exceeds them; this introduces clipping, an additional form of signal
distortion. The point at which clipping begins will depend on the
complexity (rms-to-peak value) of the input signal. For a pure sinusoid,
clipping will begin only as kdist exceeds 0.7; for a more complex input,
clipping might begin at a kdist of 0.5 or much less. kdist can exceed
the clip point by any amount, and may be greater than 1.

The shaping function can be made arbitrarily complex for extra effect.
It should generally be continuous, though this is not a requirement. It
should also be well-behaved near the mid-point, and roughly balanced
positive-negative overall, else some excessive DC offset may result. The
user might experiment with more aggressive functions to suit the
purpose. A generally positive slope allows the distorted signal to be
mixed with the source without phase cancellation.

distort is useful as an effects process, and is usually combined with
reverb and chorusing on effects busses. However, it can alternatively be
used to good effect within a single instrument.


===========================================================================
distort1                                                           *distort1*

  Description

Implementation of modified hyperbolic tangent distortion. distort1 can
be used to generate wave shaping distortion based on a modification of
the tanh function.

         exp(asig * (shape1 + pregain)) - exp(asig * (shape2 - pregain))
  aout = ---------------------------------------------------------------
         exp(asig * pregain)            + exp(-asig * pregain)

  Syntax

ares distort1 asig, kpregain, kpostgain, kshape1, kshape2[, imode]

  Initialization

imode (Csound version 5.00 and later only; optional, defaults to 0) --
scales kpregain, kpostgain, kshape1, and kshape2 for use with audio
signals in the range -32768 to 32768 (imode=0), -0dbfs to 0dbfs
(imode=1), or disables scaling of kpregain and kpostgain and scales
kshape1 by kpregain and kshape2 by -kpregain (imode=2).

  Performance

asig -- is the input signal.

kpregain -- determines the amount of gain applied to the signal before
waveshaping. A value of 1 gives slight distortion.

kpostgain -- determines the amount of gain applied to the signal after
waveshaping.

kshape1 -- determines the shape of the positive part of the curve. A
value of 0 gives a flat clip, small positive values give sloped shaping.

kshape2 -- determines the shape of the negative part of the curve.


===========================================================================
divz                                                                   *divz*

  Syntax

ares divz xa, xb, ksubst

ires divz ia, ib, isubst

kres divz ka, kb, ksubst

...divz(ka, kb, ksubst)... (no rate restriction)

  Description

Safely divides two numbers.

  Initialization

Whenever b is not zero, set the result to the value a / b; when b is
zero, set it to the value of subst instead.


===========================================================================
doppler                                                             *doppler*

  Description

A fast and robust method for approximating sound propagation, achieving
convincing Doppler shifts without having to solve equations. The method
computes frequency shifts based on reading an input delay line at a
delay time computed from the distance between source and mic and the
speed of sound. One instance of the opcode is required for each
dimension of space through which the sound source moves. If the source
sound moves at a constant speed from in front of the microphone, through
the microphone, to behind the microphone, then the output will be
frequency shifted above the source frequency at a constant frequency
while the source approaches, then discontinuously will be shifted below
the source frequency at a constant frequency as the source recedes from
the microphone. If the source sound moves at a constant speed through a
point to one side of the microphone, then the rate of change of position
will not be constant, and the familiar Doppler frequency shift typical
of a siren or engine approaching and receding along a road beside a
listener will be heard.

  Syntax

ashifted doppler asource, ksourceposition, kmicposition [, isoundspeed, ifiltercutoff]

  Initialization

isoundspeed (optional, default=340.29) -- Speed of sound in meters/second.

ifiltercutoff (optional, default=6) -- Rate of updating the position
smoothing filter, in cycles/second.

  Performance

asource -- Input signal at the sound source.

ksourceposition -- Position of the source sound in meters. The distance
between source and mic should not be changed faster than about 3/4 the
speed of sound.

kmicposition -- Position of the recording microphone in meters. The
distance between source and mic should not be changed faster than about
3/4 the speed of sound.


===========================================================================
downsamp                                                           *downsamp*

  Description

Modify a signal by down-sampling.

  Syntax

kres downsamp asig [, iwlen]

  Initialization

iwlen (optional) -- window length in samples over which the audio signal
is averaged to determine a downsampled value. Maximum length is ksmps; 0
and 1 imply no window averaging. The default value is 0.

  Performance

downsamp converts an audio signal to a control signal by downsampling.
It produces one kval for each audio control period. The optional window
invokes a simple averaging process to suppress foldover.


===========================================================================
dripwater                                                         *dripwater*

  Description

dripwater is a semi-physical model of a water drop. It is one of the
PhISEM percussion opcodes. PhISEM (Physically Informed Stochastic Event
Modeling) is an algorithmic approach for simulating collisions of
multiple independent sound producing objects.

  Syntax

ares dripwater kamp, idettack [, inum] [, idamp] [, imaxshake] [, ifreq] \
      [, ifreq1] [, ifreq2]

  Initialization

idettack -- period of time over which all sound is stopped

inum (optional) -- The number of beads, teeth, bells, timbrels, etc. If
zero, the default value is 10.

idamp (optional) -- the damping factor, as part of this equation:

damping_amount = 0.996 + (idamp * 0.002)

The default damping_amount is 0.996 which means that the default value
of idamp is 0. The maximum damping_amount is 1.0 (no damping). This
means the maximum value for idamp is 2.0.

The recommended range for idamp is usually below 75% of the maximum
value. Rasmus Ekman suggests a range of 1.4-1.75. He also suggests a
maximum value of 1.9 instead of the theoretical limit of 2.0.

imaxshake (optional, default=0) -- amount of energy to add back into the
system. The value should be in range 0 to 1.

ifreq (optional) -- the main resonant frequency. The default value is 450.

ifreq1 (optional) -- the first resonant frequency. The default value is
600.

ifreq2 (optional) -- the second resonant frequency. The default value is
750.

  Performance

kamp -- Amplitude of output. Note: As these instruments are stochastic,
this is only an approximation.


===========================================================================
dssiactivate                                                   *dssiactivate*

  Syntax

dssiactivate ihandle, ktoggle 

  Description

dssiactivate is used to activate or deactivate a DSSI or LADSPA plugin.
It calles the plugin's activate() and deactivate() functions if they are
provided.

  Initialization

ihandle - the number which identifies the plugin, generated by dssiinit.

  Performance

ktoggle - Selects between activation (ktoggle=1) and deactivation
(ktoggle=0).

dssiactivate is used to turn on and off plugins if they provide this
facility. This may help conserve CPU processing in some cases. For
consistency, all plugins must be activated to produce sound. An inactive
plugin produces silence.

Depending on the plugin's implementation, this may cause interruptions
in the realtime audio process, so use with caution.

dssiactivate may cause audio stream breakups when used in realtime, so
it is recommended to load all plugins to be used before playing.

  Warning

Please note that even if activate() and deactivate() functions are not
present in a plugin, dssiactivate must be called for the plugin to
produce sound.


===========================================================================
dssiaudio                                                         *dssiaudio*

  Syntax

[aout1, aout2, ..., aout9] dssiaudio ihandle, [ain1, ain2, ..., ain9]

  Description

dssiaudio generates audio by processing an input signal through a LADSPA
plugin.

  Initialization

ihandle - handle for the plugin returned by dssiinit

  Performance

aout1, aout2, etc - Audio ouput generated by the plugin

ain1, ain2, etc - Audio provided to the plugin for processing

dssiaudio runs a plugin on the provided audio and produces audio output.
Currently upto four inputs and outputs are provided. You should provide
signal for all the plugins audio inputs, otherwise unpredictable results
may occur. If the plugin doesn't have any input (e.g Noise generator)
you must still provide at least one input variable, which will be
ignored with a message.

Only one dssiaudio should be executed once per plugin, or strange
results may occur.


===========================================================================
dssictls                                                           *dssictls*

  Syntax

dssictls ihandle, iport, kvalue, ktrigger 

  Description

dssictls sends control values to a plugin's control port

  Initialization

ihandle - handle for the plugin returned by dssiinit

iport - control port number

  Performance

kvalue - value to be assigned to the port

ktrigger - determines whether the control information will be sent
(ktrigger = 1) or not. This is useful for thinning control information,
generating ktrigger with metro

dssictls sends control information to a LADSPA or DSSI plugin's control
port. The valid control ports and ranges are given by dssiinit . Using
values outside the ranges may produce unspecified behaviour.


===========================================================================
dssiinit                                                           *dssiinit*

  Syntax

ihandle dssiinit ilibraryname, iplugindex [, iverbose] 

  Description

dssiinit is used to load a DSSI or LADSPA plugin into memory for use
with the other dssi4cs opcodes. Both LADSPA effects and DSSI instruments
can be used.

  Initialization

ihandle - the number which identifies the plugin, to be passed to other
dssi4cs opcodes.

ilibraryname - the name of the .so (shared object) file to load.

iplugindex - The index of the plugin to be used.

iverbose (optional) - show plugin information and parameters when
loading. (default = 1)

dssiinit looks for ilibraryname on LADSPA_PATH and DSSI_PATH. One of
these variables must be set, otherwise dssiinit will return an error.
LADSPA and DSSI libraries may contain more than one plugin which must be
referenced by its index. dssiinit then attempts to find plugin index
iplugindex in the library and load the plugin into memory if it is
found. To find out which plugins you have available and their index
numbers you can use: dssilist.

If iverbose is not 0 (the default), information about the plugin
detailing its characteristics and its ports will be shown. This
information is important for opcodes like dssictls.

Plugins are set to inactive by default, so you *must* use dssiactivate
to get the plugin to produce sound. This is required even if the plugin
doesn't provide an activate() function.

dssiinit may cause audio stream breakups when used in realtime, so it is
recommended to load all plugins to be used before playing.


===========================================================================
dssilist                                                           *dssilist*

  Syntax

dssilist

  Description

dssilist checks the variables DSSI_PATH and LADSPA_PATH and lists all
plugins available in all plugin libraries there.

LADSPA and DSSI libraries may contain more than one plugin which must be
referenced by the index provided by dssilist.

This opcode produces a long printout which may interrupt realtime audio
output, so it should be run at the start of a performance.


===========================================================================
dumpk                                                                 *dumpk*

  Description

Periodically writes an orchestra control-signal value to a named
external file in a specific format.

  Syntax

dumpk  ksig, ifilname, iformat, iprd

  Initialization

ifilname -- character string (in double quotes, spaces permitted)
denoting the external file name. May either be a full path name with
target directory specified or a simple filename to be created within the
current directory

iformat -- specifies the output data format:

  * 1 = 8-bit signed char(high order 8 bits of a 16-bit integer

  * 4 = 16-bit short integers

  * 5 = 32-bit long integers

  * 6 = 32-bit floats

  * 7 = ASCII long integers

  * 8 = ASCII floats (2 decimal places)

Note that A-law and U-law output are not available, and that all formats
except the last two are binary. The output file contains no header
information.

iprd -- the period of ksig output in seconds, rounded to the nearest
orchestra control period. A value of 0 implies one control period (the
enforced minimum), which will create an output file sampled at the
orchestra control rate.

  Performance

ksig -- a control-rate signal

This opcode allows a generated control signal value to be saved in a
named external file. The file contains no self-defining header
information. But it contains a regularly sampled time series, suitable
for later input or analysis. There may be any number of dumpk opcodes in
an instrument or orchestra but each must write to a different file.


===========================================================================
dumpk2                                                               *dumpk2*

  Description

Periodically writes two orchestra control-signal values to a named
external file in a specific format.

  Syntax

dumpk2 ksig1, ksig2, ifilname, iformat, iprd

  Initialization

ifilname -- character string (in double quotes, spaces permitted)
denoting the external file name. May either be a full path name with
target directory specified or a simple filename to be created within the
current directory

iformat -- specifies the output data format:

  * 1 = 8-bit signed char(high order 8 bits of a 16-bit integer

  * 4 = 16-bit short integers

  * 5 = 32-bit long integers

  * 6 = 32-bit floats

  * 7 = ASCII long integers

  * 8 = ASCII floats (2 decimal places)

Note that A-law and U-law output are not available, and that all formats
except the last two are binary. The output file contains no header
information.

iprd -- the period of ksig output in seconds, rounded to the nearest
orchestra control period. A value of 0 implies one control period (the
enforced minimum), which will create an output file sampled at the
orchestra control rate.

  Performance

ksig1, ksig2 -- control-rate signals.

This opcode allows two generated control signal values to be saved in a
named external file. The file contains no self-defining header
information. But it contains a regularly sampled time series, suitable
for later input or analysis. There may be any number of dumpk2 opcodes
in an instrument or orchestra but each must write to a different file.


===========================================================================
dumpk3                                                               *dumpk3*

  Description

Periodically writes three orchestra control-signal values to a named
external file in a specific format.

  Syntax

dumpk3 ksig1, ksig2, ksig3, ifilname, iformat, iprd

  Initialization

ifilname -- character string (in double quotes, spaces permitted)
denoting the external file name. May either be a full path name with
target directory specified or a simple filename to be created within the
current directory

iformat -- specifies the output data format:

  * 1 = 8-bit signed char(high order 8 bits of a 16-bit integer

  * 4 = 16-bit short integers

  * 5 = 32-bit long integers

  * 6 = 32-bit floats

  * 7 = ASCII long integers

  * 8 = ASCII floats (2 decimal places)

Note that A-law and U-law output are not available, and that all formats
except the last two are binary. The output file contains no header
information.

iprd -- the period of ksig output in seconds, rounded to the nearest
orchestra control period. A value of 0 implies one control period (the
enforced minimum), which will create an output file sampled at the
orchestra control rate.

  Performance

ksig1, ksig2, ksig3 -- control-rate signals

This opcode allows three generated control signal values to be saved in
a named external file. The file contains no self-defining header
information. But it contains a regularly sampled time series, suitable
for later input or analysis. There may be any number of dumpk3 opcodes
in an instrument or orchestra but each must write to a different file.


===========================================================================
dumpk4                                                               *dumpk4*

  Description

Periodically writes four orchestra control-signal values to a named
external file in a specific format.

  Syntax

dumpk4 ksig1, ksig2, ksig3, ksig4, ifilname, iformat, iprd

  Initialization

ifilname -- character string (in double quotes, spaces permitted)
denoting the external file name. May either be a full path name with
target directory specified or a simple filename to be created within the
current directory

iformat -- specifies the output data format:

  * 1 = 8-bit signed char(high order 8 bits of a 16-bit integer

  * 4 = 16-bit short integers

  * 5 = 32-bit long integers

  * 6 = 32-bit floats

  * 7 = ASCII long integers

  * 8 = ASCII floats (2 decimal places)

Note that A-law and U-law output are not available, and that all formats
except the last two are binary. The output file contains no header
information.

iprd -- the period of ksig output in seconds, rounded to the nearest
orchestra control period. A value of 0 implies one control period (the
enforced minimum), which will create an output file sampled at the
orchestra control rate.

  Performance

ksig1, ksig2, ksig3, ksig4 -- control-rate signals

This opcode allows four generated control signal values to be saved in a
named external file. The file contains no self-defining header
information. But it contains a regularly sampled time series, suitable
for later input or analysis. There may be any number of dumpk4 opcodes
in an instrument or orchestra but each must write to a different file.


===========================================================================
duserrnd                                                           *duserrnd*

  Description

Discrete USER-defined-distribution RaNDom generator.

  Syntax

aout duserrnd ktableNum

iout duserrnd itableNum

kout duserrnd ktableNum

  Initialization

itableNum -- number of table containing the random-distribution
function. Such table is generated by the user. See GEN40, GEN41, and
GEN42. The table length does not need to be a power of 2

  Performance

ktableNum -- number of table containing the random-distribution
function. Such table is generated by the user. See GEN40, GEN41, and
GEN42. The table length does not need to be a power of 2

duserrnd (discrete user-defined-distribution random generator) generates
random values according to a discrete random distribution created by the
user. The user can create the discrete distribution histogram by using
GEN41. In order to create that table, the user has to define an
arbitrary amount of number pairs, the first number of each pair
representing a value and the second representing its probability (see
GEN41 for more details).

When used as a function, the rate of generation depends by the rate type
of input variable XtableNum. In this case it can be embedded into any
formula. Table number can be varied at k-rate, allowing to change the
distribution histogram during the performance of a single note. duserrnd
is designed be used in algorithmic music generation.

duserrnd can also be used to generate values following a set of ranges
of probabilities by using distribution functions generated by GEN42 (See
GEN42 for more details). In this case, in order to simulate continuous
ranges, the length of table XtableNum should be reasonably big, as
duserrnd does not interpolate between table elements.

For a tutorial about random distribution histograms and functions see:

  * D. Lorrain. "A panoply of stochastic cannons". In C. Roads, ed.
    1989. Music machine. Cambridge, Massachusetts: MIT press, pp. 351 -
    379.


===========================================================================
dust                                                                   *dust*

  Description

Generates random impulses from 0 to 1.

  Syntax

ares dust kamp, kdensity

kres dust kamp, kdensity

  Performance

kamp -- amplitude.

kdensity -- average number of impulses per second.


===========================================================================
dust2                                                                 *dust2*

  Description

Generates random impulses from -1 to 1.

  Syntax

ares dust2 kamp, kdensity

kres dust2 kamp, kdensity

  Performance

kamp -- amplitude.

kdensity -- average number of impulses per second.


===========================================================================
else                                                                   *else*

  Description

Executes a block of code when an "if...then" condition is false.

  Syntax

else

  Performance

else is used inside of a block of code between the "if...then" and endif
opcodes. It defines which statements are executed when a "if...then"
condition is false. Only one else statement may occur and it must be the
last conditional statement before the endif opcode.


===========================================================================
elseif                                                               *elseif*

  Description

Defines another "if...then" condition when a "if...then" condition is
false.

  Syntax

elseif xa R xb then

where label is in the same instrument block and is not an expression,
and where R is one of the Relational operators (<, =, <=, ==, !=) (and =
for convenience, see also under Conditional Values).

  Performance

elseif is used inside of a block of code between the "if...then" and
endif opcodes. When a "if...then" condition is false, it defines another
"if...then" condition to be met. Any number of elseif statements are
allowed.


===========================================================================
endif                                                                 *endif*

  Description

Closes a block of code that begins with an "if...then" statement.

  Syntax

endif

  Performance

Any block of code that begins with an "if...then" statement must end
with an endif statement.


===========================================================================
endin                                                                 *endin*

  Description

Ends the current instrument block.

  Syntax

endin

  Initialization

Ends the current instrument block.

Instruments can be defined in any order (but they will always be both
initialized and performed in ascending instrument number order).
Instrument blocks cannot be nested (i.e. one block cannot contain another).

  Note

There may be any number of instrument blocks in an orchestra.


===========================================================================
endop                                                                 *endop*

  Description

Marks the end of an user-defined opcode block.

  Syntax

endop

  Performance

The syntax of a user-defined opcode block is as follows:

opcode  name, outtypes, intypes
xinarg1 [, xinarg2] [, xinarg3] ... [xinargN]  xin
[setksmps  iksmps]
... the rest of the instrument's code.
xout  xoutarg1 [, xoutarg2] [, xoutarg3] ... [xoutargN]
endop

The new opcode can then be used with the usual syntax:

[xinarg1] [, xinarg2] ... [xinargN]  name  [xoutarg1] [, xoutarg2] ... [xoutargN] [, iksmps]


===========================================================================
envlpx                                                               *envlpx*

  Description

envlpx -- apply an envelope consisting of 3 segments:

 1. stored function rise shape

 2. modified exponential pseudo steady state

 3. exponential decay

  Syntax

ares envlpx xamp, irise, idur, idec, ifn, iatss, iatdec [, ixmod]

kres envlpx kamp, irise, idur, idec, ifn, iatss, iatdec [, ixmod]

  Initialization

irise -- rise time in seconds. A zero or negative value signifies no
rise modification.

idur -- overall duration in seconds. A zero or negative value will cause
initialization to be skipped.

idec -- decay time in seconds. Zero means no decay. An idec > idur will
cause a truncated decay.

ifn -- function table number of stored rise shape with extended guard
point.

iatss -- attenuation factor, by which the last value of the envlpx rise
is modified during the note's pseudo steady state. A factor greater than
1 causes an exponential growth and a factor less than 1 creates an
exponential decay. A factor of 1 will maintain a true steady state at
the last rise value. Note that this attenuation is not by fixed rate (as
in a piano), but is sensitive to a note's duration. However, if iatss is
negative (or if steady state < 4 k-periods) a fixed attenuation rate of
abs(iatss) per second will be used. 0 is illegal.

iatdec -- attenuation factor by which the closing steady state value is
reduced exponentially over the decay period. This value must be positive
and is normally of the order of .01. A large or excessively small value
is apt to produce a cutoff which is audible. A zero or negative value is
illegal.

ixmod (optional, between +- .9 or so) -- exponential curve modifier,
influencing the steepness of the exponential trajectory during the
steady state. Values less than zero will cause an accelerated growth or
decay towards the target (e.g. subito piano). Values greater than zero
will cause a retarded growth or decay. The default value is zero
(unmodified exponential).

  Performance

kamp, xamp -- input amplitude signal.

Rise modifications are applied for the first irise seconds, and decay
from time idur - idec. If these periods are separated in time there will
be a steady state during which amp will be modified by the first
exponential pattern. If the overall duration idur is exceeded in
performance, the final decay will continue on in the same direction,
tending asymptotically to zero.


===========================================================================
envlpxr                                                             *envlpxr*

  Description

envlpxr is the same as envlpx except that the final segment is entered
only on sensing a MIDI note release. The note is then extended by the
decay time.

  Syntax

ares envlpxr xamp, irise, idec, ifn, iatss, iatdec [, ixmod] [,irind]

kres envlpxr kamp, irise, idec, ifn, iatss, iatdec [, ixmod] [,irind]

  Initialization

irise -- rise time in seconds. A zero or negative value signifies no
rise modification.

idec -- decay time in seconds. Zero means no decay.

ifn -- function table number of stored rise shape with extended guard
point.

iatss -- attenuation factor, by which the last value of the envlpxr rise
is modified during the note's pseudo steady state. A factor greater than
1 causes an exponential growth and a factor less than 1 creates an
exponential decay. A factor of 1 will maintain a true steady state at
the last rise value. Note that this attenuation is not by fixed rate (as
in a piano), but is sensitive to a note's duration. However, if iatss is
negative (or if steady state < 4 k-periods) a fixed attenuation rate of
abs(iatss) per second will be used. 0 is illegal.

iatdec -- attenuation factor by which the closing steady state value is
reduced exponentially over the decay period. This value must be positive
and is normally of the order of .01. A large or excessively small value
is apt to produce a cutoff which is audible. A zero or negative value is
illegal.

ixmod (optional, between +- .9 or so) -- exponential curve modifier,
influencing the steepness of the exponential trajectory during the
steady state. Values less than zero will cause an accelerated growth or
decay towards the target (e.g. subito piano). Values greater than zero
will cause a retarded growth or decay. The default value is zero
(unmodified exponential).

irind (optional) -- independence flag. If left zero, the release time
(idec) will influence the extended life of the current note following a
note-off. If non-zero, the idec time is quite independent of the note
extension (see below). The default value is 0.

  Performance

kamp, xamp -- input amplitude signal.

envlpxr is an example of the special Csound “r” units that contain a
note-off sensor and release time extender. When each senses a score
event termination or a MIDI noteoff, it will immediately extend the
performance time of the current instrument by idec seconds unless it is
made independent by irind. Then it will begin a decay from wherever it
was at the time.

You can use other pre-made envelopes which start a release segment upon
receiving a note off message, like linsegr and expsegr, or you can
construct more complex envelopes using xtratim and release. Note that
you don't need to use xtratim if you are using envlpxr, since the time
is extended automatically.

These “r” units can also be modified by MIDI noteoff velocities (see
veloffs). If the irind flag is on (non-zero), the overall performance
time is unaffected by note-off and veloff data.

Multiple “r” units.  When two or more “r” units occur in the same
instrument it is usual to have only one of them influence the overall
note duration. This is normally the master amplitude unit. Other units
controlling, say, filter motion can still be sensitive to note-off
commands while not affecting the duration by making them independent
(irind non-zero). Depending on their own idec (release time) values,
independent “r” units may or may not reach their final destinations
before the instrument terminates. If they do, they will simply hold
their target values until termination. If two or more “r” units are
simultaneously master, note extension is by the greatest idec.


===========================================================================
ephasor                                                             *ephasor*

  Description

This opcode produces two outputs: a periodic phase signal (like the
phasor opcode), and a periodic exponential decaying signal. The latter
is synchronised to the former, starting at 1 and then decreasing at the
same time as the phase signal increases from 0 to 1. The rate of
exponential decay can be controlled by the second parameter.

  Syntax

aexp,aph ephasor kfreq, kR

  Performance

kfreq - the rate at which the phase and exponential signals are generated

kR - a parameter controlling the decay rate of the exponential signal, 0
< kR < 1. Lower values produce faster decays.


===========================================================================
eqfil                                                                 *eqfil*

  Description

The opcode eqfil is a 2nd order tunable equalisation filter based on
Regalia and Mitra design ("Tunable Digital Frequency Response
Equalization Filters", IEEE Trans. on Ac., Sp. and Sig Proc., 35 (1),
1987). It provides a peak/notch filter for building parametric/graphic
equalisers.

The amplitude response for this filter will be flat (=1) for kgain=1.
With kgain bigger than 1, there will be a peak at the centre frequency,
whose width is given by the kbw parameter, but outside this band, the
response will tend towards 1. Conversely, if kgain is smaller than 1, a
notch will be created around the CF.

  Syntax

asig eqfil ain, kcf, kbw, kgain[, istor]

  Initialization

istor --initial disposition of internal data space. Since filtering
incorporates a feedback loop of previous output, the initial status of
the storage space used is significant. A zero value will clear the
space; a non-zero value will allow previous information to remain. The
default value is 0.

  Performance

asig -- filtered output signal.

ain -- input signal.

kcf -- filter centre frequency.

kbw -- peak/notch bandwidth (Hz).

kgain -- peak/notch gain.


===========================================================================
evalstr                                                             *evalstr*

  Description

Evalstr compiles and runs Csound code and returns a value from the
global space (instr 0). This opcode can be also used to compile new
instruments (as compilestr).

  Syntax

ires evalstr Scode 

kres evalstr Scode, ktrig 

  Initialization

“Scode” -- a string to be compiled and evaluated.

  Performance

“ktrig” -- triggers the compilation/evaluation if non-zero.


===========================================================================
event                                                                 *event*

  Description

Generates a score event from an instrument.

  Syntax

event "scorechar", kinsnum, kdelay, kdur, [, kp4] [, kp5] [, ...]

event "scorechar", "insname", kdelay, kdur, [, kp4] [, kp5] [, ...]

  Initialization

“scorechar” -- A string (in double-quotes) representing the first
p-field in a score statement. This is usually “e”, “f”, or “i”.

“insname” -- A string (in double-quotes) representing a named instrument.

  Performance

kinsnum -- The instrument to use for the event. This corresponds to the
first p-field, p1, in a score statement.

kdelay -- When (in seconds) the event will occur from the current
performance time. This corresponds to the second p-field, p2, in a score
statement.

kdur -- How long (in seconds) the event will happen. This corresponds to
the third p-field, p3, in a score statement.

kp4, kp5, ... (optional) -- Parameters representing additional p-field
in a score statement. It starts with the fourth p-field, p4.

  Note

Note that the event opcode cannot accept string p-fields. If you need to
pass strings when instantiating an instrument, use the scoreline or
scoreline_i opcode.


===========================================================================
event_i                                                             *event_i*

  Description

Generates a score event from an instrument.

  Syntax

event_i "scorechar", iinsnum, idelay, idur, [, ip4] [, ip5] [, ...]

event_i "scorechar", "insname", idelay, idur, [, ip4] [, ip5] [, ...]

  Initialization

“scorechar” -- A string (in double-quotes) representing the first
p-field in a score statement. This is usually “e”, “f”, or “i”.

“insname” -- A string (in double-quotes) representing a named instrument.

iinsnum -- The instrument to use for the event. This corresponds to the
first p-field, p1, in a score statement.

idelay -- When (in seconds) the event will occur from the current
performance time. This corresponds to the second p-field, p2, in a score
statement.

idur -- How long (in seconds) the event will happen. This corresponds to
the third p-field, p3, in a score statement.

ip4, ip5, ... (optional) -- Parameters representing additional p-field
in a score statement. It starts with the fourth p-field, p4.

  Performance

The event is added to the queue at initialisation time.

  Note

Note that the event_i opcode cannot accept string p-fields. If you need
to pass strings when instantiating an instrument, use the scoreline or
scoreline_i opcode.


===========================================================================
exciter                                                             *exciter*

  Description

"Filtered distortion to add brilliance to a signal"

  Syntax

ares exciter asig, kfreq, kceil, kharmonics, kblend

  Initialization

  Performance

asig -- input signal

kfreq -- the lower end of the harmonics created.

kceil -- the upper end of the harmonics created.

kharmonics -- amount of harmonics in the range 0.1 - 10.

kblend -- blend between 2nd and 3rd order harmonics in the range -10 - +10.

exciter is a reimplementation of the calf exciter plugin.


===========================================================================
exitnow                                                             *exitnow*

  Description

In Csound4 calls an exit function to leave Csound as fast as possible.
On Csound5 exits back to the driving code.

  Syntax

exitnow [ivalue]

  Initialisation

Stops Csound on the initialisation cycle, returning the result ivalue,
which defaults to zero. Note that it is usual for this opcode to be
alone in an instrument.


===========================================================================
exp                                                                     *exp*

  Description

Returns e raised to the xth power.

  Syntax

exp(x) (no rate restriction)

where the argument within the parentheses may be an expression. Value
converters perform arithmetic translation from units of one kind to
units of another. The result can then be a term in a further expression.


===========================================================================
expcurve                                                           *expcurve*

  Description

Generates an exponential curve in range 0 to 1 of arbitrary steepness.
Steepness index equal to or lower than 1.0 will result in Not-a-Number
errors and cause unstable behavior.

The formula used to calculate the curve is:

(exp(x * log(y))-1) / (y-1)

where x is equal to kindex and y is equal to ksteepness.

  Syntax

kout expcurve kindex, ksteepness

  Performance

kindex -- Index value. Expected range 0 to 1.

ksteepness -- Steepness of the generated curve. Values closer to 1.0
result in a straighter line while larger values steepen the curve.

kout -- Scaled output.


===========================================================================
expon                                                                 *expon*

  Description

Trace an exponential curve between specified points.

  Syntax

ares expon ia, idur, ib

kres expon ia, idur, ib

  Initialization

ia -- starting value. Zero is illegal for exponentials.

ib -- value after idur seconds. For exponentials, must be non-zero and
must agree in sign with ia.

idur -- duration in seconds of the segment. A zero or negative value
will cause all initialization to be skipped.

  Performance

These units generate control or audio signals whose values can pass
through 2 specified points. The idur value may or may not equal the
instrument's performance time: a shorter performance will truncate the
specified pattern, while a longer one will cause the defined segment to
continue on in the same direction.


===========================================================================
exprand                                                             *exprand*

  Description

Exponential distribution random number generator (positive values only).
This is an x-class noise generator.

  Syntax

ares exprand klambda

ires exprand klambda

kres exprand klambda

  Performance

klambda -- lambda parameter for the exponential distribution.

The probablity density function of an exponential distribution is an
exponential curve, whose mean is 0.69515/lambda. For more detailed
explanation of these distributions, see:

 1. C. Dodge - T.A. Jerse 1985. Computer music. Schirmer books. pp.265 - 286

 2. D. Lorrain. A panoply of stochastic cannons. In C. Roads, ed. 1989.
    Music machine . Cambridge, Massachusetts: MIT press, pp. 351 - 379.


===========================================================================
exprandi                                                           *exprandi*

  Description

Exponential distribution random number generator with controlled
interpolation between values (positive values only). This is an x-class
noise generator.

  Syntax

ares exprandi klambda, xamp, xcps

ires exprandi klambda, xamp, xcps

kres exprandi klambda, xamp, xcps

  Performance

klambda -- lambda parameter for the exponential distribution.

The probablity density function of an exponential distribution is an
exponential curve, whose mean is 0.69515/lambda. For more detailed
explanation of these distributions, see:

 1. C. Dodge - T.A. Jerse 1985. Computer music. Schirmer books. pp.265 - 286

 2. D. Lorrain. A panoply of stochastic cannons. In C. Roads, ed. 1989.
    Music machine . Cambridge, Massachusetts: MIT press, pp. 351 - 379.

xamp -- range over which random numbers are distributed.

xcps -- the frequency which new random numbers are generated.


===========================================================================
expseg                                                               *expseg*

  Description

Trace a series of exponential segments between specified points.

  Syntax

ares expseg ia, idur1, ib [, idur2] [, ic] [...]

kres expseg ia, idur1, ib [, idur2] [, ic] [...]

  Initialization

ia -- starting value. Zero is illegal for exponentials.

ib, ic, etc. -- value after dur1 seconds, etc. For exponentials, must be
non-zero and must agree in sign with ia.

idur1 -- duration in seconds of first segment. A zero or negative value
will cause all initialization to be skipped.

idur2, idur3, etc. -- duration in seconds of subsequent segments. A zero
or negative value will terminate the initialization process with the
preceding point, permitting the last-defined line or curve to be
continued indefinitely in performance. The default is zero.

  Performance

These units generate control or audio signals whose values can pass
through 2 or more specified points. The sum of dur values may or may not
equal the instrument's performance time: a shorter performance will
truncate the specified pattern, while a longer one will cause the
last-defined segment to continue on in the same direction.

Note that the expseg opcode does not operate correctly at audio rate
when segments are shorter than a k-period. Try the expsega opcode instead.


===========================================================================
expsega                                                             *expsega*

  Description

An exponential segment generator operating at a-rate. This unit is
almost identical to expseg, but more precise when defining segments with
very short durations (i.e., in a percussive attack phase) at audio rate.

  Syntax

ares expsega ia, idur1, ib [, idur2] [, ic] [...]

  Initialization

ia -- starting value. Zero is illegal.

ib, ic, etc. -- value after idur1 seconds, etc. must be non-zero and
must agree in sign with ia.

idur1 -- duration in seconds of first segment. A zero or negative value
will cause all initialization to be skipped.

idur2, idur3, etc. -- duration in seconds of subsequent segments. A zero
or negative value will terminate the initialization process with the
preceding point, permitting the last defined line or curve to be
continued indefinitely in performance. The default is zero.

  Performance

This unit generate audio signals whose values can pass through two or
more specified points. The sum of dur values may or may not equal the
instrument's performance time. A shorter performance will truncate the
specified pattern, while a longer one will cause the last defined
segment to continue on in the same direction.


===========================================================================
expsegb                                                             *expsegb*

  Description

Trace a series of exponential segments between specified absolute points.

  Syntax

ares expsegb ia, itim1, ib [, itim2] [, ic] [...]

kres expsegb ia, itim1, ib [, itim2] [, ic] [...]

  Initialization

ia -- starting value. Zero is illegal for exponentials.

ib, ic, etc. -- value at tim1 seconds, etc. For exponentials, must be
non-zero and must agree in sign with ia.

itim1 -- time in seconds of end of first segment.

itim2, itim3, etc. -- time in seconds of subsequent ends of segments.

  Performance

These units generate control or audio signals whose values can pass
through 2 or more specified points. The last tim value may or may not
equal the instrument's performance time: a shorter performance will
truncate the specified pattern, while a longer one will cause the
last-defined segment to continue on in the same direction.

Note that the expsegb opcode does not operate correctly at audio rate
when segments are shorter than a k-period. Try the expsegba opcode instead.


===========================================================================
expsegba                                                           *expsegba*

  Description

An exponential segment generator operating at a-rate. This unit is
almost identical to expsegb, but more precise when defining segments
with very short durations (i.e., in a percussive attack phase) at audio
rate.

  Syntax

ares expsegba ia, itim1, ib [, itim2] [, ic] [...]

  Initialization

ia -- starting value. Zero is illegal.

ib, ic, etc. -- value after itim1 seconds, etc. must be non-zero and
must agree in sign with ia.

itim1 -- time in seconds at end of first segment.

itim2, itim3, etc. -- time in seconds at the end of subsequent segments.

  Performance

This unit generate audio signals whose values can pass through two or
more specified points. The final tim value may or may not equal the
instrument's performance time. A shorter performance will truncate the
specified pattern, while a longer one will cause the last defined
segment to continue on in the same direction.


===========================================================================
expsegr                                                             *expsegr*

  Description

Trace a series of exponential segments between specified points
including a release segment.

  Syntax

ares expsegr ia, idur1, ib [, idur2] [, ic] [...], irel, iz

kres expsegr ia, idur1, ib [, idur2] [, ic] [...], irel, iz

  Initialization

ia -- starting value. Zero is illegal for exponentials.

ib, ic, etc. -- value after dur1 seconds, etc. For exponentials, must be
non-zero and must agree in sign with ia.

idur1 -- duration in seconds of first segment. A zero or negative value
will cause all initialization to be skipped.

idur2, idur3, etc. -- duration in seconds of subsequent segments. A zero
or negative value will terminate the initialization process with the
preceding point, permitting the last-defined line or curve to be
continued indefinitely in performance. The default is zero.

irel, iz -- duration in seconds and final value of a note releasing
segment.

  Performance

These units generate control or audio signals whose values can pass
through 2 or more specified points. The sum of dur values may or may not
equal the instrument's performance time: a shorter performance will
truncate the specified pattern, while a longer one will cause the
last-defined segment to continue on in the same direction.

expsegr is amongst the Csound “r” units that contain a note-off sensor
and release time extender. When each senses an event termination or MIDI
noteoff, it immediately extends the performance time of the current
instrument by irel seconds, and sets out to reach the value iz by the
end of that period (no matter which segment the unit is in). “r” units
can also be modified by MIDI noteoff velocities. For two or more
extenders in an instrument, extension is by the greatest period.

You can use other pre-made envelopes which start a release segment upon
receiving a note off message, like linsegr and madsr, or you can
construct more complex envelopes using xtratim and release. Note that
you don't need to use xtratim if you are using expsegr, since the time
is extended automatically.


===========================================================================
faustaudio                                                       *faustaudio*

  Description

Faustaudio will instantiate and run a Faust program compiled with
faustcompile.

  Syntax

ihandle,a1[,a2,...] faustaudio ifac[,ain1,...] 

  Initialization

“ifac” -- a handle to a compiled Faust program, produced by faustcompile.

“ihandle” -- a handle to the Faust DSP instance, which can be used to
access its controls with faustctl.

  Performance

“ain1,...” -- input signals

“a1,...” -- output signals


===========================================================================
faustcompile                                                   *faustcompile*

  Description

Faustcompile will compile a Faust program from a string, controlled by
various arguments. Multi-line strings are accepted, using {{ }} to
enclose the string.

  Syntax

ihandle faustcompile Scode, Sargs 

  Initialization

“Scode” -- a string (in double-quotes or enclosed by {{ }}) containing a
Faust program.

“Sargs” -- a string (in double-quotes or enclosed by {{ }}) containing
Faust compiler args.


===========================================================================
faustctl                                                           *faustctl*

  Description

Faustctl will set a given control in a running faust program

  Syntax

faustctl idsp,Scontrol,kval 

  Initialization

“Scontrol” -- a string containing the control name

“idsp” -- a handle to an existing Faust DSP instance

  Performance

“kval” -- value to which the control will be set.


===========================================================================
faustgen                                                           *faustgen*

  Description

Faustgen will invoke the just-in-time compiler, instantiate and run a
Faust program.

  Syntax

ihandle,a1[,a2,...] faustgen SCode[,ain1,...] 

  Initialization

“Scode” -- a string containing a Faust program.

“ihandle” -- a handle to the Faust DSP instance, which can be used to
access its controls with faustctl.

  Performance

“ain1,...” -- input signals

“a1,...” -- output signals


===========================================================================
fareylen                                                           *fareylen*

  Description

This opcode can be used in conjunction with GENfarey. It calculates the
length of Farey Sequence F_n . Its length is given by: |F_n | = 1 + SUM
over n phi(m) where phi(m) is Euler's totient function, which gives the
number of integers ≤ m that are coprime to m.

Some values for the length of F_n given n:

n       F_n
1       2
2       3
3       5
4       7
5       11
6       13
7       19
8       23
9       29
10      33
11      43
12      47
13      59
14      65
15      73
16      81
17      97
18      103
19      121
20      129

  Syntax

kfl fareylen kfn

  Performance

The length of the identified Farey sequence is returned.

kfn -- Integer identifying the sequence.


===========================================================================
fareyleni                                                         *fareyleni*

  Description

This opcode can be used in conjunction with GENfarey. It calculates the
length of Farey Sequence F_n . Its length is given by: |F_n | = 1 + SUM
over n phi(m) where phi(m) is Euler's totient function, which gives the
number of integers ≤ m that are coprime to m.

Some values for the length of F_n given n:

n       F_n
1       2
2       3
3       5
4       7
5       11
6       13
7       19
8       23
9       29
10      33
11      43
12      47
13      59
14      65
15      73
16      81
17      97
18      103
19      121
20      129

  Syntax

ifl fareyleni ifn

  Initialisation

The length of the identified Farey sequence is returned.

ifn -- Integer identifying the sequence.


===========================================================================
ficlose                                                             *ficlose*

  Description

ficlose can be used to close a file which was opened with fiopen.

  Syntax

ficlose ihandle

ficlose Sfilename

  Initialization

ihandle -- a number which identifies this file (generated by a previous
fiopen).

Sfilename -- A string in double quotes or string variable with the
filename. The full path must be given if the file directory is not in
the system PATH and is not present in the current directory.

  Performance

ficlose closes a file which was previously opened with fiopen. ficlose
is only needed if you need to read a file written to during the same
csound performance, since only when csound ends a performance does it
close and save data in all open files. The opcode ficlose is useful for
instance if you want to save presets within files which you want to be
accesible without having to terminate csound.

  Note

If you don't need this functionality it is safer not to call ficlose,
and just let csound close the files when it exits.

If a files closed with ficlose is being accessed by another opcode (like
fout or foutk), it will be closed later when it is no longer being used.

  Warning

This opcode should be used with care, as the file handle will become
invalid, and will cause an init error when an opcode tries to access the
closed file.


===========================================================================
filebit                                                             *filebit*

  Description

Returns the number of bits in each sample in a sound file.

  Syntax

ir filebit ifilcod [, iallowraw]

  Initialization

ifilcod -- sound file to be queried

iallowraw -- (Optional) Allow raw sound files (default=1)

  Performance

filebit returns the number of bits in each sample in the sound file
ifilcod. In the case of floating point samples the value -1 is returned
for floats and -2 for doubles. For non-PCM formats the value is
negative, and based on libsndfile's format encoding.


===========================================================================
filelen                                                             *filelen*

  Description

Returns the length of a sound file.

  Syntax

ir filelen ifilcod, [iallowraw]

  Initialization

ifilcod -- sound file to be queried

iallowraw -- Allow raw sound files (default=1)

  Performance

filelen returns the length of the sound file ifilcod in seconds. filelen
can return the length of convolve and PVOC files if the "allow raw sound
file" flag is not zero (it is non-zero by default).


===========================================================================
filenchnls                                                       *filenchnls*

  Description

Returns the number of channels in a sound file.

  Syntax

ir filenchnls ifilcod [, iallowraw]

  Initialization

ifilcod -- sound file to be queried

iallowraw -- (Optional) Allow raw sound files (default=1)

  Performance

filenchnls returns the number of channels in the sound file ifilcod.
filechnls can return the number of channels of convolve and PVOC files
if the iallowraw flag is not zero (it is non-zero by default).


===========================================================================
filepeak                                                           *filepeak*

  Description

Returns the peak absolute value of a sound file.

  Syntax

ir filepeak ifilcod [, ichnl]

  Initialization

ifilcod -- sound file to be queried

ichnl (optional, default=0) -- channel to be used in calculating the
peak value. Default is 0.

  * ichnl = 0 returns peak value of all channels

  * ichnl > 0 returns peak value of ichnl

  Performance

filepeak returns the peak absolute value of the sound file ifilcod.


===========================================================================
filescal                                                           *filescal*

  Description

filescal implements phase-locked vocoder processing from disk files,
resampling if necessary.

This opcode allows for time and frequency-independent scaling. Time is
advanced internally, but controlled by a tempo scaling parameter; when
an onset is detected, timescaling is momentarily stopped to avoid
smearing of attacks. The quality of the effect is generally improved
with phase locking switched on.

filescal will also scale pitch, independently of frequency, using a
transposition factor (k-rate).

  Syntax

asig[,asig2] filescal ktimescal, kamp, kpitch, Sfile, klock [,ifftsize, idecim, ithresh]

  Initialization

Sfile -- source soundfile, mono or stereo files are allowed, but need to
match the number of outputs.

ifftsize -- FFT size (power-of-two), defaults to 2048.

idecim -- decimation, defaults to 4 (meaning hopsize = fftsize/4)

idbthresh -- threshold based on dB power spectrum ratio between two
successive windows. A detected ratio above it will cancel timescaling
momentarily, to avoid smearing (defaults to 1)

  Performance

ktimescal -- timescaling ratio, < 1 stretch, > 1 contract. Non-negative
numbers only.

kamp -- amplitude scaling

kpitch -- grain pitch scaling (1=normal pitch, < 1 lower, > 1 higher;
negative, backwards)

klock -- 0 or 1, to switch phase-locking on/off


===========================================================================
filesr                                                               *filesr*

  Description

Returns the sample rate of a sound file.

  Syntax

ir filesr ifilcod [, iallowraw]

  Initialization

ifilcod -- sound file to be queried

iallowraw -- (Optional) Allow raw sound files (default=1)

  Performance

filesr returns the sample rate of the sound file ifilcod. filesr can
return the sample rate of convolve and PVOC files if the iallowraw flag
is not zero (it is non-zero by default).


===========================================================================
filevalid                                                         *filevalid*

  Description

Returns 1 if the sound file is valid, or 0 if not.

  Syntax

ir filevalid ifilcod

  Initialization

ifilcod -- sound file to be queried

  Performance

filevalid returns 1 if the sound file ifilcod can be used.


===========================================================================
fillarray                                                         *fillarray*

  Description

Generate a vector (one-dimensional k-rate array) with a sequence of
numeric or string values.

  Syntax

karray[] fillarray ival1, ival2,.....ivaln

karray fillarray ival1, ival2,.....ivaln

  Initialization

ival1,...ivaln -- values to place in the vector.

In the second form the answer array must be pre-declared, and it may be
a multidimensional array which if filled in row-major order.


===========================================================================
fft                                                                     *fft*

  Description

Applies a forward Fast Fourier Transform to a complex-valued input
1-dimensional array producing a complex-valued output. The output is
another array containing the complex-valued signal, and both arrays are
arranged in interleaved real-imaginary format. The output array will
have the same size as the input, and the transform size will be
equivalent to half of the length of the array. Non-power-of-two
transforms are limited to even sizes with not too many factors.

  Syntax

kout[] fft kin[]

  Performance

kout[] -- output array containing the complex-valued output. It will be
created if it does not exist.

kin[] -- input array containing the complex-valued input.


===========================================================================
filter2                                                             *filter2*

  Description

General purpose custom filter with no time-varying pole control. The
filter coefficients implement the following difference equation:

(1)*y(n) = b0*x[n] + b1*x[n-1] +...+ bM*x[n-M] - a1*y[n-1] -...- aN*y[n-N]

the system function for which is represented by:

           B(Z)      b0 + b1*Z^-1   + ... + bM*Z^-M
  H(Z)  =  ----  =  --------------------------
           A(Z)       1 + a1*Z^-1   + ... + aN*Z^-N

  Syntax

ares filter2 asig, iM, iN, ib0, ib1, ..., ibM, ia1, ia2, ..., iaN

kres filter2 ksig, iM, iN, ib0, ib1, ..., ibM, ia1, ia2, ..., iaN

  Initialization

At initialization the number of zeros and poles of the filter are
specified along with the corresponding zero and pole coefficients. The
coefficients must be obtained by an external filter-design application
such as Matlab and specified directly or loaded into a table via GEN01.

  Performance

Thefilter2 opcodes perform filtering using a transposed form-II digital
filter lattice with no time-varying control.

Since filter2 implements generalized recursive filters, it can be used
to specify a large range of general DSP algorithms. For example, a
digital waveguide can be implemented for musical instrument modeling
using a pair of delayr and delayw opcodes in conjunction with the
filter2 opcode.


===========================================================================
fin                                                                     *fin*

  Description

Read signals from a file at a-rate.

  Syntax

fin ifilename, iskipframes, iformat, ain1 [, ain2] [, ain3] [,...]

fin ifilename, iskipframes, iformat, arr[]

  Initialization

ifilename -- input file name (can be a string or a handle number
generated by fiopen).

iskipframes -- number of frames to skip at the start (every frame
contains a sample of each channel)

iformat -- a number specifying the input file format for headerless
files. If a header is found, this argument is ignored.

  * 0 - 32 bit floating points without header

  * 1 - 16 bit integers without header

  Performance

fin (file input) is the complement of fout: it reads a multichannel file
to generate audio rate signals. The user must be sure that the number of
channels of the input file is the same as the number of ainX arguments.

  Note

Please note that since this opcode generates its output using input
parameters (on the right side of the opcode), these variables must be
initialized before use, otherwise a 'used before defined' error will
occur. You can use the init opcode for this.


===========================================================================
fini                                                                   *fini*

  Description

Read signals from a file at i-rate.

  Syntax

fini ifilename, iskipframes, iformat, in1 [, in2] [, in3] [, ...]

  Initialization

ifilename -- input file name (can be a string or a handle number
generated by fiopen)

iskipframes -- number of frames to skip at the start (every frame
contains a sample of each channel)

iformat -- a number specifying the input file format. If a header is
found, this argument is ignored.

  * 0 - floating points in text format (loop; see below)

  * 1 - floating points in text format (no loop; see below)

  * 2 - 32 bit floating points in binary format (no loop)

  Performance

fini is the complement of fouti and foutir. It reads the values each
time the corresponding instrument note is activated. When iformat is set
to 0 and the end of file is reached, the file pointer is zeroed. This
restarts the scan from the beginning. When iformat is set to 1 or 2, no
looping is enabled and at the end of file the corresponding variables
will be filled with zeroes.

  Note

Please note that since this opcode generates its output using input
parameters (on the right side of the opcode), these variables must be
initialized before use, otherwise a 'used before defined' error will
occur. You can use the init opcode for this.


===========================================================================
fink                                                                   *fink*

  Description

Read signals from a file at k-rate.

  Syntax

fink ifilename, iskipframes, iformat, kin1 [, kin2] [, kin3] [,...]

  Initialization

ifilename -- input file name (can be a string or a handle number
generated by fiopen)

iskipframes -- number of frames to skip at the start (every frame
contains a sample of each channel)

iformat -- a number specifying the input file format. If a header is
found, this argument is ignored.

  * 0 - 32 bit floating points without header

  * 1 - 16 bit integers without header

  Performance

fink is the same as fin but operates at k-rate.

  Note

Please note that since this opcode generates its output using input
parameters (on the right side of the opcode), these variables must be
initialized before use, otherwise a 'used before defined' error will
occur. You can use the init opcode for this.


===========================================================================
fiopen                                                               *fiopen*

  Description

fiopen can be used to open a file in one of the specified modes.

  Syntax

ihandle fiopen ifilename, imode

  Initialization

ihandle -- a number which specifies this file.

ifilename -- the target file's name (in double-quotes).

imode -- choose the mode of opening the file. imode can be a value
chosen among the following:

  * 0 - open a text file for writing

  * 1 - open a text file for reading

  * 2 - open a binary file for writing

  * 3 - open a binary file for reading

  Performance

fiopen opens a file to be used by the fout family of opcodes. It is
safer to use it in the header section, external to any instruments. It
returns a number, ihandle, which unequivocally refers to the opened file.

If fiopen is called on an already open file, it just returns the same
handle again, and does not close the file.

Notice that fout and foutk can use either a string containing a file
pathname, or a handle-number generated by fiopen. Whereas, with fouti
and foutir, the target file can be only specified by means of a
handle-number.


===========================================================================
flanger                                                             *flanger*

  Description

A user controlled flanger.

  Syntax

ares flanger asig, adel, kfeedback [, imaxd]

  Initialization

imaxd(optional) -- maximum delay in seconds (needed for inital memory
allocation)

  Performance

asig -- input signal

adel -- delay in seconds

kfeedback -- feedback amount (in normal tasks this should not exceed 1,
even if bigger values are allowed)

This unit is useful for generating choruses and flangers. The delay must
be varied at a-rate, for example by connecting adel to an oscillator
output. The feedback can vary at k-rate. This opcode is implemented to
allow kr different than sr (else delay could not be lower than ksmps)
enhancing realtime performance. This unit is very similar to wguide1,
the only difference is flanger does not have the lowpass filter or the
requirement that the delay be varied at a-rate.


===========================================================================
flashtxt                                                           *flashtxt*

  Description

Allows text to be displayed from instruments like sliders etc. (only on
Unix and Windows at present)

  Syntax

flashtxt  iwhich, String

  Initialization

iwhich -- the number of the window.

String -- the string to be displayed.

  Performance

Note that this opcode is not available on Windows due to the
implimentation of pipes on that system

A window is created, identified by the iwhich argument, with the text
string displayed. If the text is replaced by a number then the window id
deleted. Note that the text windows are globally numbered so different
instruments can change the text, and the window survives the instance of
the instrument.


===========================================================================
FLbox                                                                 *FLbox*

  Description

A FLTK widget that displays text inside of a box.

  Syntax

ihandle FLbox "label", itype, ifont, isize, iwidth, iheight, ix, iy [, image]

  Initialization

ihandle -- a handle value (an integer number) that unequivocally
references a corresponding widget. This is used by other opcodes that
modify a widget's properties (see Modifying FLTK Widget Appearance). It
is automatically output by FLbox and must not be set by the user label.
(The user label is a double-quoted string containing some user-provided
text placed near the widget.)

“label” -- a double-quoted string containing some user-provided text,
placed near corresponding widget.

Notice that with FLbox, it is not necessary to call the FLsetTextType
opcode at all in order to use a symbol. In this case, it is sufficient
to set a label starting with “@” followed by the proper formatting string.

The following symbols are supported:

FLTK label supported symbols.

FLTK label supported symbols.

The @ sign may be followed by the following optional “formatting”
characters, in this order:

 1. “#” forces square scaling rather than distortion to the widget's shape.

 2. +[1-9] or -[1-9] tweaks the scaling a little bigger or smaller.

 3. [1-9] rotates by a multiple of 45 degrees. “6” does nothing, the
    others point in the direction of that key on a numeric keypad.

itype -- an integer number denoting the appearance of the widget.

The following values are legal for itype:

  * 1 - flat box

  * 2 - up box

  * 3 - down box

  * 4 - thin up box

  * 5 - thin down box

  * 6 - engraved box

  * 7 - embossed box

  * 8 - border box

  * 9 - shadow box

  * 10 - rounded box

  * 11 - rounded box with shadow

  * 12 - rounded flat box

  * 13 - rounded up box

  * 14 - rounded down box

  * 15 - diamond up box

  * 16 - diamond down box

  * 17 - oval box

  * 18 - oval shadow box

  * 19 - oval flat box

ifont -- an integer number denoting the font of FLbox.

ifont argument to set the font type. The following values are legal for
ifont:

  * 1 - helvetica (same as "Arial" under Windows)

  * 2 - helvetica bold

  * 3 - helvetica italic

  * 4 - helvetica bold italic

  * 5 - courier

  * 6 - courier bold

  * 7 - courier italic

  * 8 - courier bold italic

  * 9 - times

  * 10 - times bold

  * 11 - times italic

  * 12 - times bold italic

  * 13 - symbol

  * 14 - screen

  * 15 - screen bold

  * 16 - dingbats

isize -- size of the font.

iwidth -- width of widget.

iheight -- height of widget.

ix -- horizontal position of the upper left corner of the valuator,
relative to the upper left corner of corresponding window. (Expressed in
pixels.)

iy -- vertical position of the upper left corner of the valuator,
relative to the upper left corner of corresponding window. (Expressed in
pixels.)

image -- a handle referring to an eventual image opened with bmopen
opcode. If it is set, it allows a skin for that widget.

  Note about the bmopen opcode

Although the documentation mentions the bmopen opcode, it has not been
implemented in Csound 4.22.

  Performance

FLbox is useful to show some text in a window. The text is bounded by a
box, whose aspect depends on itype argument.

Note that FLbox is not a valuator and its value is fixed. Its value
cannot be modified.


===========================================================================
FLbutBank                                                         *FLbutBank*

  Description

A FLTK widget opcode that creates a bank of buttons.

  Syntax

kout, ihandle FLbutBank itype, inumx, inumy, iwidth, iheight, ix, iy, \
      iopcode [, kp1] [, kp2] [, kp3] [, kp4] [, kp5] [....] [, kpN]

  Initialization

ihandle -- a handle value (an integer number) that unequivocally
references a corresponding widget. This is used by other opcodes that
modify a widget's properties (see Modifying FLTK Widget Appearance). It
is automatically output by FLbutBank and must not be set by the user
label. (The user label is a double-quoted string containing some
user-provided text placed near the widget.)

itype -- an integer number denoting the appearance of the widget. The
valid numbers are:

  * 1 - normal button

  * 2 - light button

  * 3 - check button

  * 4 - round button

You can add 20 to the value to create a "plastic" type button. (Note
that there is no Platic Round button. i.e. if you set type to 24 it will
look exactly like type 23).

inumx -- number of buttons in each row of the bank.

inumy -- number of buttons in each column of the bank

ix -- horizontal position of upper left corner of the valuator, relative
to the upper left corner of corresponding window, expressed in pixels

iy -- vertical position of upper left corner of the valuator, relative
to the upper left corner of corresponding window, expressed in pixels

iopcode -- score opcode type. You have to provide the ascii code of the
letter corresponding to the score opcode. At present time only “i”
(ascii code 105) score statements are supported. A zero value refers to
a default value of “i”. So both 0 and 105 activates the i opcode. A
value of -1 disables this opcode feature.

  Performance

kout -- output value

kp1, kp2, ..., kpN -- arguments of the activated instruments.

The FLbutBank opcode creates a bank of buttons. For example, the
following line:

gkButton,ihb1  FLbutBank  22, 8, 8, 380, 180, 50, 350, 0, 7, 0, 0, 5000, 6000

will create the this bank:

FLbutBank.

FLbutBank.

A click to a button checks that button. It may also uncheck a previous
checked button belonging to the same bank. So the behaviour is always
that of radio-buttons. Notice that each button is labeled with a
progressive number. The kout argument is filled with that number when
corresponding button is checked.

FLbutBank not only outputs a value but can also activate (or schedule)
an instrument provided by the user each time a button is pressed. If the
iopcode argument is set to a negative number, no instrument is activated
so this feature is optional. In order to activate an instrument, iopcode
must be set to 0 or to 105 (the ascii code of character “i”, referring
to the i score opcode). P-fields of the activated instrument are kp1
(instrument number), kp2 (action time), kp3 (duration) and so on with
user p-fields.

The itype argument sets the type of buttons identically to the FLbutton
opcode. By adding 10 to the itype argument (i.e. by setting 11 for type
1, 12 for type 2, 13 for type 3 and 14 for type 4), it is possible to
skip the current FLbutBank value when getting/setting snapshots (see
General FLTK Widget-related Opcodes). You can also add 10 to "plastic"
button types (31 for type 1, 32 for type 2, etc.)

FLbutBank is very useful to retrieve snapshots.


===========================================================================
FLbutton                                                           *FLbutton*

  Description

A FLTK widget opcode that creates a button.

  Syntax

kout, ihandle FLbutton "label", ion, ioff, itype, iwidth, iheight, ix, \
      iy, iopcode [, kp1] [, kp2] [, kp3] [, kp4] [, kp5] [....] [, kpN]

  Initialization

ihandle -- a handle value (an integer number) that unequivocally
references a corresponding widget. This is used by other opcodes that
modify a widget's properties (see Modifying FLTK Widget Appearance). It
is automatically output by FLbutton and must not be set by the user
label. (The user label is a double-quoted string containing some
user-provided text placed near the widget.)

“label” -- a double-quoted string containing some user-provided text,
placed near the corresponding widget.

Notice that with FLbutton, it is not necessary to call the FLsetTextType
opcode at all in order to use a symbol. In this case, it is sufficient
to set a label starting with “@” followed by the proper formatting string.

The following symbols are supported:

FLTK label supported symbols.

FLTK label supported symbols.

The @ sign may be followed by the following optional “formatting”
characters, in this order:

 1. “#” forces square scaling rather than distortion to the widget's shape.

 2. +[1-9] or -[1-9] tweaks the scaling a little bigger or smaller.

 3. [1-9] rotates by a multiple of 45 degrees. “6” does nothing, the
    others point in the direction of that key on a numeric keypad.

ion -- value output when the button is checked.

ioff -- value output when the button is unchecked.

itype -- an integer number denoting the appearance of the widget.

Several kind of buttons are possible, according to the value of itype
argument:

  * 1 - normal button

  * 2 - light button

  * 3 - check button

  * 4 - round button

You can add 20 to the value to create a "plastic" type button. (Note
that there is no Platic Round button. i.e. if you set type to 24 it will
look exactly like type 23).

This is the appearance of the buttons:

FLbutton.

FLbutton.

iwidth -- width of widget.

iheight -- height of widget.

ix -- horizontal position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

iy -- vertical position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

iopcode -- score opcode type. You have to provide the ascii code of the
letter corresponding to the score opcode. At present time only “i”
(ascii code 105) score statements are supported. A zero value refers to
a default value of “i”. So both 0 and 105 activates the i opcode. A
value of -1 disables this opcode feature.

  Performance

kout -- output value

kp1, kp2, ..., kpN -- arguments of the activated instruments.

Buttons of type 2, 3, and 4 also output (kout argument) the value
contained in the ion argument when checked, and that contained in ioff
argument when unchecked.

By adding 10 to itype argument (i.e. by setting 11 for type 1, 12 for
type 2, 13 for type 3 and 14 for type 4) it is possible to skip the
button value when getting/setting snapshots (see later section).
FLbutton not only outputs a value, but can also activate (or schedule)
an instrument provided by the user each time a button is pressed. You
can also add 10 to "plastic" button types (31 for type 1, 32 for type 2,
etc.)

If the iopcode argument is set to a negative number, no instrument is
activated. So this feature is optional. In order to activate an
instrument, iopcode must be set to 0 or to 105 (the ascii code of
character “i”, referring to the i score opcode).

P-fields of the activated instrument are kp1 (instrument number), kp2
(action time), kp3 (duration) and so on with user p-fields. Notice that
in dual state buttons (light button, check button and round button), the
instrument is activated only when button state changes from unchecked to
checked (not when passing from checked to unchecked).


===========================================================================
FLcloseButton                                                 *FLcloseButton*

  Description

A FLTK widget opcode that creates a button that will close the panel
window it is a part of.

  Syntax

ihandle FLcloseButton "label", iwidth, iheight, ix, iy

  Initialization

ihandle -- a handle value (an integer number) that unequivocally
references a corresponding widget. This is used by other opcodes that
modify a widget's properties (see Modifying FLTK Widget Appearance). It
is automatically output by FLcloseButton and must not be set by the user
label. (The user label is a double-quoted string containing some
user-provided text placed near the widget.)

“label” -- a double-quoted string containing some user-provided text,
placed near the corresponding widget.

Notice that with FLcloseButton, it is not necessary to call the
FLsetTextType opcode at all in order to use a symbol. In this case, it
is sufficient to set a label starting with “@” followed by the proper
formatting string.

The following symbols are supported:

FLTK label supported symbols.

FLTK label supported symbols.

The @ sign may be followed by the following optional “formatting”
characters, in this order:

 1. “#” forces square scaling rather than distortion to the widget's shape.

 2. +[1-9] or -[1-9] tweaks the scaling a little bigger or smaller.

 3. [1-9] rotates by a multiple of 45 degrees. “6” does nothing, the
    others point in the direction of that key on a numeric keypad.

iwidth -- width of widget.

iheight -- height of widget.

ix -- horizontal position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

iy -- vertical position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).


===========================================================================
FLcolor                                                             *FLcolor*

  Description

Sets the primary colors to RGB values given by the user.

  Syntax

FLcolor ired, igreen, iblue [, ired2, igreen2, iblue2]

  Initialization

ired -- The red color of the target widget. The range for each RGB
component is 0-255

igreen -- The green color of the target widget. The range for each RGB
component is 0-255

iblue -- The blue color of the target widget. The range for each RGB
component is 0-255

ired2 -- The red component for the secondary color of the target widget.
The range for each RGB component is 0-255

igreen2 -- The green component for the secondary color of the target
widget. The range for each RGB component is 0-255

iblue2 -- The blue component for the secondary color of the target
widget. The range for each RGB component is 0-255

  Performance

These opcodes modify the appearance of other widgets. There are two
types of such opcodes, those that don't contain the ihandle argument
which affect all subsequently declared widgets, and those with ihandle
which affect only a target widget previously defined.

FLcolor sets the primary colors to RGB values given by the user. This
opcode affects the primary color of (almost) all widgets defined next
its location. User can put several instances of FLcolor in front of each
widget he intend to modify. However, to modify a single widget, it would
be better to use the opcode belonging to the second type (i.e. those
containing ihandle argument).

FLcolor is designed to modify the colors of a group of related widgets
that assume the same color. The influence of FLcolor on subsequent
widgets can be turned off by using -1 as the only argument of the
opcode. Also, using -2 (or -3) as the only value of FLcolor makes all
next widget colors randomly selected. The difference is that -2 selects
a light random color, while -3 selects a dark random color.

Using ired2, igreen2, iblue2 is equivalent to using a separate FLcolor2.


===========================================================================
FLcolor2                                                           *FLcolor2*

  Description

FLcolor2 is the same of FLcolor except it affects the secondary
(selection) color.

  Syntax

FLcolor2 ired, igreen, iblue

  Initialization

ired -- The red color of the target widget. The range for each RGB
component is 0-255

igreen -- The green color of the target widget. The range for each RGB
component is 0-255

iblue -- The blue color of the target widget. The range for each RGB
component is 0-255

  Performance

These opcodes modify the appearance of other widgets. There are two
types of such opcodes: those that don't contain the ihandle argument
which affect all subsequently declared widgets, and those with ihandle
which affect only a target widget previously defined.

FLcolor2 is the same of FLcolor except it affects the secondary
(selection) color. Setting it to -1 turns off the influence of FLcolor2
on subsequent widgets. A value of -2 (or -3) makes all next widget
secondary colors randomly selected. The difference is that -2 selects a
light random color, while -3 selects a dark random color.


===========================================================================
FLcount                                                             *FLcount*

  Description

Allows the user to increase/decrease a value with mouse clicks on a
corresponding arrow button.

  Syntax

kout, ihandle FLcount "label", imin, imax, istep1, istep2, itype, \
      iwidth, iheight, ix, iy, iopcode [, kp1] [, kp2] [, kp3] [...] [, kpN]

  Initialization

ihandle -- a handle value (an integer number) that unequivocally
references a corresponding widget. Used by further opcodes that changes
some valuator's properties. It is automatically set by the corresponding
valuator.

“label” -- a double-quoted string containing some user-provided text,
placed near the corresponding widget.

imin -- minimum value of output range

imax -- maximum value of output range

istep1 -- a floating-point number indicating the increment of valuator
value corresponding to of each mouse click. istep1 is for fine adjustments.

istep2 -- a floating-point number indicating the increment of valuator
value corresponding to of each mouse click. istep2 is for coarse
adjustments.

itype -- an integer number denoting the appearance of the valuator.

iwidth -- width of widget.

iheight -- height of widget.

ix -- horizontal position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

iy -- vertical position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

iopcode -- score opcode type. You have to provide the ascii code of the
letter corresponding to the score opcode. At present time only “i”
(ascii code 105) score statements are supported. A zero value refers to
a default value of “i”. So both 0 and 105 activates the i opcode. A
value of -1 disables this opcode feature.

  Performance

kout -- output value

kp1, kp2, ..., kpN -- arguments of the activated instruments.

FLcount allows the user to increase/decrease a value with mouse clicks
on corresponding arrow buttons:

FLcount.

FLcount.

There are two kind of arrow buttons, for larger and smaller steps.
Notice that FLcount not only outputs a value and a handle, but can also
activate (schedule) an instrument provided by the user each time a
button is pressed. P-fields of the activated instrument are kp1
(instrument number), kp2 (action time), kp3 (duration) and so on with
user p-fields. If the iopcode argument is set to a negative number, no
instrument is activated. So this feature is optional.


===========================================================================
FLexecButton                                                   *FLexecButton*

  Description

A FLTK widget opcode that creates a button that executes a command.
Useful for opening up HTML documentation as About text or to start a
separate program from an FLTK widget interface.

  Warning

Because any command can be executed, the user is advised to be very
careful when using this opcode and when running orchestras by others
using this opcode.

  Syntax

ihandle FLexecButton "command", iwidth, iheight, ix, iy

  Initialization

ihandle -- a handle value (an integer number) that unequivocally
references a corresponding widget. This is used by other opcodes that
modify a widget's properties (see Modifying FLTK Widget Appearance). It
is automatically output by FLexecButton.

“command” -- a double-quoted string containing a command to execute.

Notice that with FLexecButton, the default text for the button is
"About" and it is necessary to call the FLsetText opcode to change the
text of the button.

iwidth -- width of widget.

iheight -- height of widget.

ix -- horizontal position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

iy -- vertical position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).


===========================================================================
FLgetsnap                                                         *FLgetsnap*

  Description

Retrieves a previously stored snapshot (in memory), i.e. sets all
valuator to the corresponding values stored in that snaphot.

  Syntax

inumsnap FLgetsnap index [, igroup]

  Initialization

inumsnap -- current number of snapshots.

index -- a number referring unequivocally to a snapshot. Several
snapshots can be stored in the same bank.

igroup -- (optional) an integer number referring to a snapshot-related
group of widget. It allows to get/set, or to load/save the state of a
subset of valuators. Default value is zero that refers to the first
group. The group number is determined by the opcode FLsetSnapGroup.

  Note

The igroup parameter has not been yet fully implemented in the current
version of csound. Please do not rely on it yet.

  Performance

FLgetsnap retrieves a previously stored snapshot (in memory), i.e. sets
all valuator to the corresponding values stored in that snapshot. The
index argument unequivocally must refer to an already existing snapshot.
If the index argument refers to an empty snapshot or to a snapshot that
doesn't exist, no action is done. FLsetsnap outputs the current number
of snapshots (inumsnap argument).

For purposes of snapshot saving, widgets can be grouped, so that
snapshots affect only a defined group of widgets. The opcode
FLsetSnapGroup is used to specify the group for all widgets declared
after it, until the next FLsetSnapGroup statement.


===========================================================================
FLgroup                                                             *FLgroup*

  Description

A FLTK container opcode that groups child widgets.

  Syntax

FLgroup "label", iwidth, iheight, ix, iy [, iborder] [, image]

  Initialization

“label” -- a double-quoted string containing some user-provided text,
placed near the corresponding widget.

iwidth -- width of widget.

iheight -- height of widget.

ix -- horizontal position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

iy -- vertical position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

iborder (optional, default=0) -- border type of the container. It is
expressed by means of an integer number chosen from the following:

  * 0 - no border

  * 1 - down box border

  * 2 - up box border

  * 3 - engraved border

  * 4 - embossed border

  * 5 - black line border

  * 6 - thin down border

  * 7 - thin up border

If the integer number doesn't match any of the previous values, no
border is provided as the default.

image (optional) -- a handle referring to an eventual image opened with
the bmopen opcode. If it is set, it allows a skin for that widget.

  Note about the bmopen opcode

Although the documentation mentions the bmopen opcode, it has not been
implemented in Csound 4.22.

  Performance

Containers are useful to format the graphic appearance of the widgets.
The most important container is FLpanel, that actually creates a window.
It can be filled with other containers and/or valuators or other kinds
of widgets.

There are no k-rate arguments in containers.


===========================================================================
FLgroupEnd                                                       *FLgroupEnd*

  Description

Marks the end of a group of FLTK child widgets.

  Syntax

FLgroupEnd

  Performance

Containers are useful to format the graphic appearance of the widgets.
The most important container is FLpanel, that actually creates a window.
It can be filled with other containers and/or valuators or other kinds
of widgets.

There are no k-rate arguments in containers.


===========================================================================
FLgroup_end                                                     *FLgroup_end*

  Description

Marks the end of a group of FLTK child widgets. This is another name for
FLgroupEnd provides for compatibility. See FLgroupEnd


===========================================================================
FLhide                                                               *FLhide*

  Description

Hides the target FLTK widget, making it invisible.

  Syntax

FLhide ihandle

  Initialization

ihandle -- a handle value (an integer number) that unequivocally
references a corresponding widget. This is used by other opcodes that
modify a widget's properties (see Modifying FLTK Widget Appearance).

  Performance

FLhide hides target widget, making it invisible.


===========================================================================
FLhvsBox                                                           *FLhvsBox*

  Description

FLhvsBox displays a box with a grid useful for visualizing
two-dimensional Hyper Vectorial Synthesis.

  Syntax

ihandle FLhvsBox inumlinesX, inumlinesY, iwidth, iheight, ix, iy

  Initialization

ihandle – an integer number used a univocally-defined handle for
identifying a specific HVS box (see below).

inumlinesX, inumlinesY - number of vertical and horizontal lines
delimiting the HVS squared areas

iwidth, iheight - width and height of the HVS box

ix, iy - the position of the HVS box

  Performance

FLhvsBox is a widget able to visualize current position of the HVS
cursor in an HVS box (i.e. a squared area containing a grid). The number
of horizontal and vertical lines of the grid can be defined with the
inumlinesX, inumlinesY arguments. This opcode has to be declared inside
an FLpanel - FLpanelEnd block. See the entry for hvs2 for an example of
usage of FLhvsBox.

FLhvsBoxSetValue is used to set the cursor position of an FLhvsBox widget.


===========================================================================
FLhvsBoxSetValue                                           *FLhvsBoxSetValue*

  Description

FLhvsBoxSetValue sets the cursor position of a previously-declared
FLhvsBox widget.

  Syntax

FLhvsBox kx, ky, ihandle

  Initialization

ihandle – an integer number used a univocally-defined handle for
identifying a specific HVS box (see below).

  Performance

kx, ky– the coordinates of the HVS cursor position to be set.

FLhvsBoxSetValue sets the cursor position of a previously-declared
FLhvsBox widget. The kx and ky arguments, denoting the cursor position,
have to be expressed in normalized values (0 to 1 range).

See the entry for hvs2 for an example of usage of FLhvsBoxSetValue.


===========================================================================
FLjoy                                                                 *FLjoy*

  Description

FLjoy is a squared area that allows the user to modify two output values
at the same time. It acts like a joystick.

  Syntax

koutx, kouty, ihandlex, ihandley FLjoy "label", iminx, imaxx, iminy, \
      imaxy, iexpx, iexpy, idispx, idispy, iwidth, iheight, ix, iy

  Initialization

ihandlex -- a handle value (an integer number) that unequivocally
references a corresponding widget. Used by further opcodes that changes
some valuator's properties. It is automatically set by the corresponding
valuator.

ihandley -- a handle value (an integer number) that unequivocally
references a corresponding widget. Used by further opcodes that changes
some valuator's properties. It is automatically set by the corresponding
valuator.

“label” -- a double-quoted string containing some user-provided text,
placed near the corresponding widget.

iminx -- minimum x value of output range

imaxx -- maximum x value of output range

iminy -- minimum y value of output range

imaxy -- maximum y value of output range

iwidth -- width of widget.

idispx -- a handle value that was output from a previous instance of the
FLvalue opcode to display the current value of the current valuator in
the FLvalue widget itself. If the user doesn't want to use this feature
that displays current values, it must be set to a negative number by the
user.

idispy -- a handle value that was output from a previous instance of the
FLvalue opcode to display the current value of the current valuator in
the FLvalue widget itself. If the user doesn't want to use this feature
that displays current values, it must be set to a negative number by the
user.

iexpx -- an integer number denoting the behaviour of valuator:

  * 0 = valuator output is linear

  * -1 = valuator output is exponential

All other positive numbers for iexpx indicate the number of an existing
table that is used for indexing. Linear interpolation is provided in
table indexing. A negative table number suppresses interpolation.

iexpy -- an integer number denoting the behaviour of valuator:

  * 0 = valuator output is linear

  * -1 = valuator output is exponential

All other positive numbers for iexpy indicate the number of an existing
table that is used for indexing. Linear interpolation is provided in
table indexing. A negative table number suppresses interpolation.

  IMPORTANT!

Notice that the tables used by valuators must be created with the ftgen
opcode and placed in the orchestra before the corresponding valuator.
They can not placed in the score. In fact, tables placed in the score
are created later than the initialization of the opcodes placed in the
header section of the orchestra.

iheight -- height of widget.

ix -- horizontal position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

iy -- vertical position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

  Performance

koutx -- x output value

kouty -- y output value


===========================================================================
FLkeyIn                                                             *FLkeyIn*

  Description

FLkeyIn informs about the status of a key pressed by the user on the
alphanumeric keyboard when an FLTK panel has got the focus.

  Syntax

kascii FLkeyIn [ifn]

  Initialization

ifn – (optional, default value is zero) set the behavior of FLkeyIn (see
below).

  Performance

kascii - the ascii value of last pressed key. If the key is pressed, the
value is positive, when the key is released the value is negative.

FLkeyIn is useful to know whether a key has been pressed on the computer
keyboard. The behavior of this opcode depends on the optional ifn argument.

If ifn = 0 (default), FLkeyIn outputs the ascii code of the last pressed
key. If it is a special key (ctrl, shift, alt, f1-f12 etc.), a value of
256 is added to the output value in order to distinguish it from normal
keys. The output will continue to output the last key value, until a new
key is pressed or released. Notice that the output will be negative when
a key is depressed.

If ifn is set to the number of an already-allocated table having at
least 512 elements, then the table element having index equal to the
ascii code of the key pressed is set to 1, all other table elements are
set to 0. This allows to check the state of a certain key or set of keys.

Be aware that you must set the ikbdcapture parameter to something other
than 0 on a designated FLpanel for FLkeyIn to capture keyboard events
from that panel.

  Note

FLkeyIn works internally at k-rate, so it can't be used in the header as
other FLTK opcodes. It must be used inside an instrument.


===========================================================================
FLknob                                                               *FLknob*

  Description

A FLTK widget opcode that creates a knob.

  Syntax

kout, ihandle FLknob "label", imin, imax, iexp, itype, idisp, iwidth, \
      ix, iy [, icursorsize]

  Initialization

ihandle -- a handle value (an integer number) that unequivocally
references a corresponding widget. This is used by other opcodes that
modify a widget's properties (see Modifying FLTK Widget Appearance). It
is automatically utput by FLknob and must not be set by the user label.
(The user label is a double-quoted string containing some user-provided
text placed near the widget.)

“label” -- a double-quoted string containing some user-provided text,
placed near the corresponding widget.

imin -- minimum value of output range.

imax -- maximum value of output range.

iexp -- an integer number denoting the behaviour of valuator:

  * 0 = valuator output is linear

  * -1 = valuator output is exponential

All other positive numbers for iexp indicate the number of an existing
table that is used for indexing. Linear interpolation is provided in
table indexing. A negative table number suppresses interpolation.

  IMPORTANT!

Notice that the tables used by valuators must be created with the ftgen
opcode and placed in the orchestra before the corresponding valuator.
They can not placed in the score. In fact, tables placed in the score
are created later than the initialization of the opcodes placed in the
header section of the orchestra.

itype -- an integer number denoting the appearance of the valuator.

The itype argument can be set to the following values:

  * 1 - a 3-D knob

  * 2 - a pie-like knob

  * 3 - a clock-like knob

  * 4 - a flat knob

A 3-D knob.

A 3-D knob.

A pie knob.

A pie knob.

A clock knob.

A clock knob.

A flat knob.

A flat knob.

idisp -- a handle value that was output from a previous instance of the
FLvalue opcode to display the current value of the current valuator in
the FLvalue widget itself. If the user doesn't want to use this feature
that displays current values, it must be set to a negative number by the
user.

iwidth -- width of widget.

iheight -- height of widget.

ix -- horizontal position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

iy -- vertical position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

icursorsize (optional) -- If FLknob's itype is set to 1 (3D knob), this
parameter controls the size of knob cursor.

  Performance

kout -- output value

FLknob puts a knob in the corresponding container.


===========================================================================
FLlabel                                                             *FLlabel*

  Description

Modifies a set of parameters related to the text label appearence of a
widget (i.e. size, font, alignment and color of corresponding text).

  Syntax

FLlabel isize, ifont, ialign, ired, igreen, iblue

  Initialization

isize -- size of the font of the target widget. Normal values are in the
order of 15. Greater numbers enlarge font size, while smaller numbers
reduce it.

ifont -- sets the the font type of the label of a widget.

Legal values for ifont argument are:

  * 1 - Helvetica (same as Arial under Windows)

  * 2 - Helvetica Bold

  * 3 - Helvetica Italic

  * 4 - Helvetica Bold Italic

  * 5 - Courier

  * 6 - Courier Bold

  * 7 - Courier Italic

  * 8 - Courier Bold Italic

  * 9 - Times

  * 10 - Times Bold

  * 11 - Times Italic

  * 12 - Times Bold Italic

  * 13 - Symbol

  * 14 - Screen

  * 15 - Screen Bold

  * 16 - Dingbats

ialign -- sets the alignment of the label text of the widget.

Legal values for ialign argument are:

  * 1 - align center

  * 2 - align top

  * 3 - align bottom

  * 4 - align left

  * 5 - align right

  * 6 - align top-left

  * 7 - align top-right

  * 8 - align bottom-left

  * 9 - align bottom-right

ired -- The red color of the target widget. The range for each RGB
component is 0-255

igreen -- The green color of the target widget. The range for each RGB
component is 0-255

iblue -- The blue color of the target widget. The range for each RGB
component is 0-255

  Performance

FLlabel modifies a set of parameters related to the text label
appearance of a widget, i.e. size, font, alignment and color of
corresponding text. This opcode affects (almost) all widgets defined
next its location. A user can put several instances of FLlabel in front
of each widget he intends to modify. However, to modify a particular
widget, it is better to use the opcode belonging to the second type
(i.e. those containing the ihandle argument).

The influence of FLlabel on the next widget can be turned off by using
-1 as its only argument. FLlabel is designed to modify text attributes
of a group of related widgets.


===========================================================================
FLloadsnap                                                       *FLloadsnap*

  Description

FLloadsnap loads all the snapshots contained in a file into the memory
bank of the current orchestra.

  Syntax

FLloadsnap "filename" [, igroup]

  Initialization

"filename" -- a double-quoted string corresponding to a file to load a
bank of snapshots.

igroup -- (optional) an integer number referring to a snapshot-related
group of widget. It allows to get/set, or to load/save the state of a
subset of valuators. Default value is zero that refers to the first
group. The group number is determined by the opcode FLsetSnapGroup.

  Note

The igroup parameter has not been yet fully implemented in the current
version of csound. Please do not rely on it yet.

  Performance

FLloadsnap loads all snapshots contained in filename into the memory
bank of current orchestra.

For purposes of snapshot saving, widgets can be grouped, so that
snapshots affect only a defined group of widgets. The opcode
FLsetSnapGroup is used to specify the group for all widgets declared
after it, until the next FLsetSnapGroup statement.


===========================================================================
FLmouse                                                             *FLmouse*

  Description

FLmouse returns the coordinates of the mouse position within an FLTK
panel and the state of the three mouse buttons.

  Syntax

kx, ky, kb1, kb2, kb3 FLmouse [imode]

  Initialization

imode – (optional, default = 0) Determines the mode for mouse location
reporting.

  * 0 - Absolute position normalized to range 0-1

  * 1 - Absolute raw pixel position

  * 2 - Raw pixel position, relative to FLTK panel

  Performance

kx, ky – the mouse coordinates, whose range depends on the imode
argument (see above).

kb1, kb2, kb3 – the states of the mouse buttons, 1 when corresponding
button is pressed, 0 when the button is not pressed.

FLmouse returns the coordinates of the mouse position and the state of
the three mouse buttons. The coordinates can be retrieved in three modes
depending on the imode argument value (see above). Modes 0 and 1 report
mouse position in relation to the complete screen (Absolute mode), while
mode 2, reports the pixel position within an FLTK panel. Notice that
FLmouse is only active when the mouse cursor passes on an FLpanel area.


===========================================================================
flooper                                                             *flooper*

  Description

This opcode reads audio from a function table and plays it back in a
loop with user-defined start time, duration and crossfade time. It also
allows the pitch of the loop to be controlled, including reversed
playback. It accepts non-power-of-two tables, such as
deferred-allocation GEN01 tables, with one or two channels.

  Syntax

asig1[, asig2] flooper kamp, kpitch, istart, idur, ifad, ifn

  Initialization

istart -- loop start pos in seconds

idur -- loop duration in seconds

ifad -- crossfade duration in seconds

ifn -- function table number, generally created using GEN01

  Performance

asig[,asig2] -- output sig (mono or stereo)

kamp -- amplitude control

kpitch -- pitch control (transposition ratio); negative values play the
loop back in reverse


===========================================================================
flooper2                                                           *flooper2*

  Description

This opcode implements a crossfading looper with variable loop
parameters and three looping modes, optionally using a table for its
crossfade shape. It accepts non-power-of-two tables for its source
sounds, such as deferred-allocation GEN01 tables, with one or two channels.

  Syntax

asig1[,asig2] flooper2 kamp, kpitch, kloopstart, kloopend, kcrossfade, ifn \
      [, istart, imode, ifenv, iskip]

  Initialization

ifn -- sound source function table number, generally created using GEN01

istart -- playback start pos in seconds

imode -- loop modes: 0 forward, 1 backward, 2 back-and-forth [def: 0]

ifenv -- if non-zero, crossfade envelope shape table number. The
default, 0, sets the crossfade to linear.

iskip -- if 1, the opcode initialisation is skipped, for tied notes,
performance continues from the position in the loop where the previous
note stopped. The default, 0, does not skip initialisation

  Performance

asig1[, asig2] -- output sig (mono or stereo).

kamp -- amplitude control

kpitch -- pitch control (transposition ratio); negative values are not
allowed.

kloopstart -- loop start point (secs). Note that although k-rate, loop
parameters such as this are only updated once per loop cycle.

kloopend -- loop end point (secs), updated once per loop cycle.

kcrossfade -- crossfade length (secs), updated once per loop cycle and
limited to loop length.

Mode 1 for imode will only loop backwards from the end point to the
start point.


===========================================================================
floor                                                                 *floor*

  Description

Returns the largest integer not greater than x

  Syntax

floor(x) (init-, control-, or audio-rate arg allowed)

where the argument within the parentheses may be an expression. Value
converters perform arithmetic translation from units of one kind to
units of another. The result can then be a term in a further expression.


===========================================================================
FLpack                                                               *FLpack*

  Description

FLpack provides the functionality of compressing and aligning widgets.

  Syntax

FLpack iwidth, iheight, ix, iy, itype, ispace, iborder

  Initialization

iwidth -- width of widget.

iheight -- height of widget.

ix -- horizontal position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

iy -- vertical position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

itype -- an integer number that modifies the appearance of the target
widget.

The itype argument expresses the type of packing:

  * 0 - vertical

  * 1 - horizontal

ispace -- sets the space between the widgets.

iborder -- border type of the container. It is expressed by means of an
integer number chosen from the following:

  * 0 - no border

  * 1 - down box border

  * 2 - up box border

  * 3 - engraved border

  * 4 - embossed border

  * 5 - black line border

  * 6 - thin down border

  * 7 - thin up border

  Performance

FLpack provides the functionality of compressing and aligning widgets.

Containers are useful to format the graphic appearance of the widgets.
The most important container is FLpanel, that actually creates a window.
It can be filled with other containers and/or valuators or other kinds
of widgets.

There are no k-rate arguments in containers.


===========================================================================
FLpackEnd                                                         *FLpackEnd*

  Description

Marks the end of a group of compressed or aligned FLTK widgets.

  Syntax

FLpackEnd

  Performance

Containers are useful to format the graphic appearance of the widgets.
The most important container is FLpanel, that actually creates a window.
It can be filled with other containers and/or valuators or other kinds
of widgets.

There are no k-rate arguments in containers.


===========================================================================
FLpack_end                                                       *FLpack_end*

  Description

Marks the end of a group of compressed or aligned FLTK widgets. This is
another name for FLpackEnd provided for compatibility. See FLpackEnd


===========================================================================
FLpanel                                                             *FLpanel*

  Description

Creates a window that contains FLTK widgets.

  Syntax

FLpanel "label", iwidth, iheight [, ix] [, iy] [, iborder] [, ikbdcapture] [, iclose]

  Initialization

“label” -- a double-quoted string containing some user-provided text,
placed near the corresponding widget.

iwidth -- width of widget.

iheight -- height of widget.

ix (optional) -- horizontal position of upper left corner of the
valuator, relative to the upper left corner of corresponding window
(expressed in pixels).

iy (optional) -- vertical position of upper left corner of the valuator,
relative to the upper left corner of corresponding window (expressed in
pixels).

iborder (optional) -- border type of the container. It is expressed by
means of an integer number chosen from the following:

  * 0 - no border

  * 1 - down box border

  * 2 - up box border

  * 3 - engraved border

  * 4 - embossed border

  * 5 - black line border

  * 6 - thin down border

  * 7 - thin up border

ikbdcapture (default = 0) -- If this flag is set to 1, keyboard events
are captured by the window (for use with sensekey and FLkeyIn)

iclose (default = 0) -- If this flag is set to anything other than 0,
the close button of the window is disabled, and the window cannot be
closed by the user directly. It will close when csound exits.

  Performance

Containers are useful to format the graphic appearance of the widgets.
The most important container is FLpanel, that actually creates a window.
It can be filled with other containers and/or valuators or other kinds
of widgets.

There are no k-rate arguments in containers.

FLpanel creates a window. It must be followed by the opcode FLpanelEnd
when all widgets internal to it are declared. For example:

         FLpanel    "PanelPluto",450,550,100,100 ;***** start of container
gk1, ih1 FLslider   "FLslider 1", 500, 1000, 2 ,1, -1, 300,15, 20,50
gk2, ih2 FLslider   "FLslider 2", 300, 5000, 2 ,3, -1, 300,15, 20,100
gk3, ih3 FLslider   "FLslider 3", 350, 1000, 2 ,5, -1, 300,15, 20,150
gk4, ih4 FLslider   "FLslider 4", 250, 5000, 1 ,11,-1, 300,30, 20,200
         FLpanelEnd ;***** end of container

will output the following result:

FLpanel.

FLpanel.

If the ikbdcapture flag is set, the window captures keyboard events, and
sends them to all sensekey. This flag modifies the behavior of sensekey,
and makes it receive events from the FLTK window instead of stdin.


===========================================================================
FLpanelEnd                                                       *FLpanelEnd*

  Description

Marks the end of a group of FLTK widgets contained inside of a window
(panel).

  Syntax

FLpanelEnd

  Performance

Containers are useful to format the graphic appearance of the widgets.
The most important container is FLpanel, that actually creates a window.
It can be filled with other containers and/or valuators or other kinds
of widgets.

There are no k-rate arguments in containers.


===========================================================================
FLpanel_end                                                     *FLpanel_end*

  Description

Marks the end of a group of FLTK widgets contained inside of a window
(panel). This is another name for FLpanelEnd provided for compatibility.
See FLpanelEnd


===========================================================================
FLprintk                                                           *FLprintk*

  Description

FLprintk is similar to printk but shows values of a k-rate signal in a
text field instead of on the console.

  Syntax

FLprintk itime, kval, idisp

  Initialization

itime -- how much time in seconds is to elapse between updated displays.

idisp -- a handle value that was output from a previous instance of the
FLvalue opcode to display the current value of the current valuator in
the FLvalue widget itself. If the user doesn't want to use this feature
that displays current values, it must be set to a negative number by the
user.

  Performance

kval -- k-rate signal to be displayed.

FLprintk is similar to printk, but shows values of a k-rate signal in a
text field instead of showing it in the console. The idisp argument must
be filled with the ihandle return value of a previous FLvalue opcode.
While FLvalue should be placed in the header section of an orchestra
inside an FLpanel/FLpanelEnd block, FLprintk must be placed inside an
instrument to operate correctly. For this reason, it slows down
performance and should be used for debugging purposes only.


===========================================================================
FLprintk2                                                         *FLprintk2*

  Description

FLprintk2 is similar to FLprintk but shows a k-rate variable's value
only when it changes.

  Syntax

FLprintk2 kval, idisp

  Initialization

idisp -- a handle value that was output from a previous instance of the
FLvalue opcode to display the current value of the current valuator in
the FLvalue widget itself. If the user doesn't want to use this feature
that displays current values, it must be set to a negative number by the
user.

  Performance

kval -- k-rate signal to be displayed.

FLprintk2 is similar to FLprintk, but shows the k-rate variable's value
only each time it changes. Useful for monitoring MIDI control changes
when using sliders. It should be used for debugging purposes only, since
it slows-down performance.


===========================================================================
FLroller                                                           *FLroller*

  Description

FLroller is a sort of knob, but put transversally.

  Syntax

kout, ihandle FLroller "label", imin, imax, istep, iexp, itype, idisp, \
      iwidth, iheight, ix, iy

  Initialization

ihandle -- a handle value (an integer number) that unequivocally
references a corresponding widget. This is used by other opcodes that
modify a widget's properties (see Modifying FLTK Widget Appearance). It
is automatically output by FLroller and must not be set by the user
label. (The user label is a double-quoted string containing some
user-provided text placed near the widget.)

“label” -- a double-quoted string containing some user-provided text,
placed near the corresponding widget.

imin -- minimum value of output range.

imax -- maximum value of output range.

istep -- a floating-point number indicating the increment of valuator
value corresponding to of each mouse click. The istep argument allows
the user to arbitrarily slow roller's motion, enabling arbitrary precision.

iexp -- an integer number denoting the behaviour of valuator:

  * 0 = valuator output is linear

  * -1 = valuator output is exponential

All other positive numbers for iexp indicate the number of an existing
table that is used for indexing. Linear interpolation is provided in
table indexing. A negative table number suppresses interpolation.

  IMPORTANT!

Notice that the tables used by valuators must be created with the ftgen
opcode and placed in the orchestra before the corresponding valuator.
They can not placed in the score. In fact, tables placed in the score
are created later than the initialization of the opcodes placed in the
header section of the orchestra.

itype -- an integer number denoting the appearance of the valuator.

The itype argument can be set to the following values:

  * 1 - horizontal roller

  * 2 - vertical roller

idisp -- a handle value that was output from a previous instance of the
FLvalue opcode to display the current value of the current valuator in
the FLvalue widget itself. If the user doesn't want to use this feature
that displays current values, it must be set to a negative number by the
user.

iwidth -- width of widget.

iheight -- height of widget.

ix -- horizontal position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

iy -- vertical position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

  Performance

kout -- output value

FLroller is a sort of knob, but put transversally:

FLroller.

FLroller.


===========================================================================
FLrun                                                                 *FLrun*

  Description

Starts the FLTK widget thread.

  Syntax

FLrun

  Performance

This opcode must be located at the end of all widget declarations. It
has no arguments, and its purpose is to start the thread related to
widgets. Widgets would not operate if FLrun is missing.


===========================================================================
FLsavesnap                                                       *FLsavesnap*

  Description

FLsavesnap saves all snapshots currently created (i.e. the entire memory
bank) into a file.

  Syntax

FLsavesnap "filename" [, igroup]

  Initialization

“filename” -- a double-quoted string corresponding to a file to store a
bank of snapshots.

igroup -- (optional) an integer number referring to a snapshot-related
group of widget. It allows to get/set, or to load/save the state of a
subset of valuators. Default value is zero that refers to the first
group. The group number is determined by the opcode FLsetSnapGroup.

  Note

The igroup parameter has not been yet fully implemented in the current
version of csound. Please do not rely on it yet.

  Performance

FLsavesnap saves all snapshots currently created (i.e. the entire memory
bank) into a file whose name is filename. Since the file is a text file,
snapshot values can also be edited manually by means of a text editor.
The format of the data stored in the file is the following (at present
time, this could be changed in next Csound version):

----------- 0 -----------
FLvalue 0 0 1 0 ""
FLvalue 0 0 1 0 ""
FLvalue 0 0 1 0 ""
FLslider 331.946 80 5000 -1 "frequency of the first oscillator"
FLslider 385.923 80 5000 -1 "frequency of the second oscillator"
FLslider 80 80 5000 -1 "frequency of the third oscillator"
FLcount 0 0 10 0 "this index must point to the location number where snapshot is stored"
FLbutton 0 0 1 0 "Store snapshot to current index"
FLbutton 0 0 1 0 "Save snapshot bank to disk"
FLbutton 0 0 1 0 "Load snapshot bank from disk"
FLbox 0 0 1 0 ""
----------- 1 -----------
FLvalue 0 0 1 0 ""
FLvalue 0 0 1 0 ""
FLvalue 0 0 1 0 ""
FLslider 819.72 80 5000 -1 "frequency of the first oscillator"
FLslider 385.923 80 5000 -1 "frequency of the second oscillator"
FLslider 80 80 5000 -1 "frequency of the third oscillator"
FLcount 1 0 10 0 "this index must point to the location number where snapshot is stored"
FLbutton 0 0 1 0 "Store snapshot to current index"
FLbutton 0 0 1 0 "Save snapshot bank to disk"
FLbutton 0 0 1 0 "Load snapshot bank from disk"
FLbox 0 0 1 0 ""
----------- 2 -----------
..... etc...
----------- 3 -----------
..... etc...
---------------------------

As you can see, each snapshot contain several lines. Each snapshot is
separated from previous and next snapshot by a line of this kind:

"----------- snapshot Num -----------"

Then there are several lines containing data. Each of these lines
corresponds to a widget.

The first field of each line is an unquoted string containing opcode
name corresponding to that widget. Second field is a number that
expresses current value of a snapshot. In current version, this is the
only field that can be modified manually. The third and fourth fields
shows minimum and maximum values allowed for that valuator. The fifth
field is a special number that indicates if the valuator is linear
(value 0), exponential (value -1), or is indexed by a table
interpolating values (negative table numbers) or non-interpolating
(positive table numbers). The last field is a quoted string with the
label of the widget. Last line of the file is always

"---------------------------"

.

Note that FLvalue andFLbox are not valuators and their values are fixed,
so they cannot be modified.

For purposes of snapshot saving, widgets can be grouped, so that
snapshots affect only a defined group of widgets. The opcode
FLsetSnapGroup is used to specify the group for all widgets declared
after it, until the next FLsetSnapGroup statement.


===========================================================================
FLscroll                                                           *FLscroll*

  Description

FLscroll adds scroll bars to an area.

  Syntax

FLscroll iwidth, iheight [, ix] [, iy]

  Initialization

iwidth -- width of widget.

iheight -- height of widget.

ix (optional) -- horizontal position of upper left corner of the
valuator, relative to the upper left corner of corresponding window
(expressed in pixels).

iy (optional) -- vertical position of upper left corner of the valuator,
relative to the upper left corner of corresponding window (expressed in
pixels).

  Performance

Containers are useful to format the graphic appearance of the widgets.
The most important container is FLpanel, that actually creates a window.
It can be filled with other containers and/or valuators or other kinds
of widgets.

There are no k-rate arguments in containers.

FLscroll adds scroll bars to an area. Normally you must set arguments
iwidth and iheight equal to that of the parent window or other parent
container. ix and iy are optional since they normally are set to zero.
For example the following code:

         FLpanel    "PanelPluto",400,300,100,100
         FLscroll   400,300
gk1, ih1 FLslider   "FLslider 1", 500, 1000, 2 ,1, -1, 300,15, 20,50
gk2, ih2 FLslider   "FLslider 2", 300, 5000, 2 ,3, -1, 300,15, 20,100
gk3, ih3 FLslider   "FLslider 3", 350, 1000, 2 ,5, -1, 300,15, 20,150
gk4, ih4 FLslider   "FLslider 4", 250, 5000, 1 ,11,-1, 300,30, 20,200
         FLscrollEnd
         FLpanelEnd

will show scroll bars, when the main window size is reduced:

FLscroll.

FLscroll.


===========================================================================
FLscrollEnd                                                     *FLscrollEnd*

  Description

A FLTK opcode that marks the end of an area with scrollbars.

  Syntax

FLscrollEnd

  Performance

Containers are useful to format the graphic appearance of the widgets.
The most important container is FLpanel, that actually creates a window.
It can be filled with other containers and/or valuators or other kinds
of widgets.

There are no k-rate arguments in containers.


===========================================================================
FLscroll_end                                                   *FLscroll_end*

  Description

A FLTK opcode that marks the end of an area with scrollbars. This is
another name for FLscrollEnd provided for compatibility. See FLscrollEnd


===========================================================================
FLsetAlign                                                       *FLsetAlign*

  Description

FLsetAlign sets the text alignment of the label of the target widget.

  Syntax

FLsetAlign ialign, ihandle

  Initialization

ialign -- sets the alignment of the label text of widgets.

The legal values for the ialign argument are:

  * 1 - align center

  * 2 - align top

  * 3 - align bottom

  * 4 - align left

  * 5 - align right

  * 6 - align top-left

  * 7 - align top-right

  * 8 - align bottom-left

  * 9 - align bottom-right

ihandle -- an integer number (used as unique identifier) taken from the
output of a previously located widget opcode (which corresponds to the
target widget). It is used to unequivocally identify the widget when
modifying its appearance with this class of opcodes. The user must not
set the ihandle value directly, otherwise a Csound crash will occur.


===========================================================================
FLsetBox                                                           *FLsetBox*

  Description

FLsetBox sets the appearance of a box surrounding the target widget.

  Syntax

FLsetBox itype, ihandle

  Initialization

itype -- an integer number that modify the appearance of the target widget.

Legal values for the itype argument are:

  * 1 - flat box

  * 2 - up box

  * 3 - down box

  * 4 - thin up box

  * 5 - thin down box

  * 6 - engraved box

  * 7 - embossed box

  * 8 - border box

  * 9 - shadow box

  * 10 - rounded box

  * 11 - rounded box with shadow

  * 12 - rounded flat box

  * 13 - rounded up box

  * 14 - rounded down box

  * 15 - diamond up box

  * 16 - diamond down box

  * 17 - oval box

  * 18 - oval shadow box

  * 19 - oval flat box

ihandle -- an integer number (used as unique identifier) taken from the
output of a previously located widget opcode (which corresponds to the
target widget). It is used to unequivocally identify the widget when
modifying its appearance with this class of opcodes. The user must not
set the ihandle value directly, otherwise a Csound crash will occur.


===========================================================================
FLsetColor                                                       *FLsetColor*

  Description

FLsetColor sets the primary color of the target widget.

  Syntax

FLsetColor ired, igreen, iblue, ihandle

  Initialization

ired -- The red color of the target widget. The range for each RGB
component is 0-255

igreen -- The green color of the target widget. The range for each RGB
component is 0-255

iblue -- The blue color of the target widget. The range for each RGB
component is 0-255

ihandle -- an integer number (used as unique identifier) taken from the
output of a previously located widget opcode (which corresponds to the
target widget). It is used to unequivocally identify the widget when
modifying its appearance with this class of opcodes. The user must not
set the ihandle value directly, otherwise a Csound crash will occur.


===========================================================================
FLsetColor2                                                     *FLsetColor2*

  Description

FLsetColor2 sets the secondary (or selection) color of the target widget.

  Syntax

FLsetColor2 ired, igreen, iblue, ihandle

  Initialization

ired -- The red color of the target widget. The range for each RGB
component is 0-255

igreen -- The green color of the target widget. The range for each RGB
component is 0-255

iblue -- The blue color of the target widget. The range for each RGB
component is 0-255

ihandle -- an integer number (used as unique identifier) taken from the
output of a previously located widget opcode (which corresponds to the
target widget). It is used to unequivocally identify the widget when
modifying its appearance with this class of opcodes. The user must not
set the ihandle value directly, otherwise a Csound crash will occur.


===========================================================================
FLsetFont                                                         *FLsetFont*

  Description

FLsetFont sets the font type of the target widget.

  Syntax

FLsetFont ifont, ihandle

  Initialization

ifont -- sets the the font type of the label of a widget.

Legal values for ifont argument are:

  * 1 - Helvetica (same as Arial under Windows)

  * 2 - Helvetica Bold

  * 3 - Helvetica Italic

  * 4 - Helvetica Bold Italic

  * 5 - Courier

  * 6 - Courier Bold

  * 7 - Courier Italic

  * 8 - Courier Bold Italic

  * 9 - Times

  * 10 - Times Bold

  * 11 - Times Italic

  * 12 - Times Bold Italic

  * 13 - Symbol

  * 14 - Screen

  * 15 - Screen Bold

  * 16 - Dingbats

ihandle -- an integer number (used as unique identifier) taken from the
output of a previously located widget opcode (which corresponds to the
target widget). It is used to unequivocally identify the widget when
modifying its appearance with this class of opcodes. The user must not
set the ihandle value directly, otherwise a Csound crash will occur.


===========================================================================
FLsetPosition                                                 *FLsetPosition*

  Description

FLsetPosition sets the position of the target widget according to the ix
and iy arguments.

  Syntax

FLsetPosition ix, iy, ihandle

  Initialization

ix -- horizontal position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

iy -- vertical position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

ihandle -- an integer number (used as unique identifier) taken from the
output of a previously located widget opcode (which corresponds to the
target widget). It is used to unequivocally identify the widget when
modifying its appearance with this class of opcodes. The user must not
set the ihandle value directly, otherwise a Csound crash will occur.


===========================================================================
FLsetSize                                                         *FLsetSize*

  Description

FLsetSize resizes the target widget (not the size of its text) according
to the iwidth and iheight arguments.

  Syntax

FLsetSize iwidth, iheight, ihandle

  Initialization

iwidth -- width of widget.

iheight -- height of widget.

ihandle -- an integer number (used as unique identifier) taken from the
output of a previously located widget opcode (which corresponds to the
target widget). It is used to unequivocally identify the widget when
modifying its appearance with this class of opcodes. The user must not
set the ihandle value directly, otherwise a Csound crash will occur.


===========================================================================
FLsetsnap                                                         *FLsetsnap*

  Description

FLsetsnap stores the current status of all valuators present in the
orchestra into a snapshot location (in memory).

  Syntax

inumsnap, inumval FLsetsnap index [, ifn, igroup]

  Initialization

inumsnap -- current number of snapshots.

inumval -- number of valuators (whose value is stored in a snapshot)
present in current orchestra.

index -- a number referring unequivocally to a snapshot. Several
snapshots can be stored in the same bank.

ifn (optional) -- optional argument referring to an already allocated
table, to store values of a snapshot.

igroup -- (optional) an integer number referring to a snapshot-related
group of widget. It allows to get/set, or to load/save the state of a
subset of valuators. Default value is zero that refers to the first
group. The group number is determined by the opcode FLsetSnapGroup.

  Note

The igroup parameter has not been yet fully implemented in the current
version of csound. Please do not rely on it yet.

  Performance

The FLsetsnap opcode stores current status of all valuators present in
the orchestra into a snapshot location (in memory). Any number of
snapshots can be stored in the current bank. Banks are structures that
only exist in memory, there are no other reference to them other that
they can be accessed by FLsetsnap, FLsavesnap, FLloadsnap and FLgetsnap
opcodes. Only a single bank can be present in memory.

If the optional ifn argument refers to an already allocated and valid
table, the snapshot will be stored in the table instead of in the bank.
So that table can be accessed from other Csound opcodes.

The index argument unequivocally refers to a determinate snapshot. If
the value of index refers to a previously stored snapshot, all its old
values will be replaced with current ones. If index refers to a snapshot
that doesn't exist, a new snapshot will be created. If the index value
is not adjacent with that of a previously created snapshot, some empty
snapshots will be created. For example, if a location with index 0
contains the only and unique snapshot present in a bank and the user
stores a new snapshot using index 5, all locations between 1 and 4 will
automatically contain empty snapshots. Empty snapshots don't contain any
data and are neutral.

FLsetsnap outputs the current number of snapshots (the inumsnap
argument) and the total number of values stored in each snapshot
(inumval). inumval is equal to the number of valuators present in the
orchestra.

For purposes of snapshot saving, widgets can be grouped, so that
snapshots affect only a defined group of widgets. The opcode
FLsetSnapGroup is used to specify the group for all widgets declared
after it, until the next FLsetSnapGroup statement.


===========================================================================
FLsetSnapGroup                                               *FLsetSnapGroup*

  Description

FLsetSnapGroup determines the snapshot group of valuators declared after
it.

  Syntax

FLsetSnapGroup igroup

  Initialization

igroup -- (optional) an integer number referring to a snapshot-related
group of widget. It allows to get/set, or to load/save the state of a
subset of valuators.

  Note

The igroup parameter has not been yet fully implemented in the current
version of csound. Please do not rely on it yet.

  Performance

For purposes of snapshot saving, widgets can be grouped, so that
snapshots affect only a defined group of widgets. The opcode
FLsetSnapGroup is used to specify the group for all widgets declared
after it, until the next FLsetSnapGroup statement.

FLsetSnapGroup determines the snapshot group of a declared valuator. To
make a valuator belong to a stated group, you have to place
FLsetSnapGroup just before the declaration of the widget itself. The
group stated by FLsetSnapGroup lasts for all valuators declared after
it, until a new FLsetSnapGroup statement with a different group is
encountered. If no FLsetSnapGroup statement are present in an orchestra,
the default group for all widgets will be group zero.


===========================================================================
FLsetText                                                         *FLsetText*

  Description

FLsetText sets the label of the target widget to the double-quoted text
string provided with the itext argument.

  Syntax

FLsetText "itext", ihandle

  Initialization

“itext” -- a double-quoted string denoting the text of the label of the
widget.

ihandle -- an integer number (used as unique identifier) taken from the
output of a previously located widget opcode (which corresponds to the
target widget). It is used to unequivocally identify the widget when
modifying its appearance with this class of opcodes. The user must not
set the ihandle value directly, otherwise a Csound crash will occur.


===========================================================================
FLsetTextColor                                               *FLsetTextColor*

  Description

FLsetTextColor sets the color of the text label of the target widget.

  Syntax

FLsetTextColor ired, iblue, igreen, ihandle

  Initialization

ired -- The red color of the target widget. The range for each RGB
component is 0-255

igreen -- The green color of the target widget. The range for each RGB
component is 0-255

iblue -- The blue color of the target widget. The range for each RGB
component is 0-255

ihandle -- an integer number (used as unique identifier) taken from the
output of a previously located widget opcode (which corresponds to the
target widget). It is used to unequivocally identify the widget when
modifying its appearance with this class of opcodes. The user must not
set the ihandle value directly, otherwise a Csound crash will occur.


===========================================================================
FLsetTextSize                                                 *FLsetTextSize*

  Description

FLsetTextSize sets the size of the text label of the target widget.

  Syntax

FLsetTextSize isize, ihandle

  Initialization

isize -- size of the font of the target widget. Normal values are in the
order of 15. Greater numbers enlarge font size, while smaller numbers
reduce it.

ihandle -- an integer number (used as unique identifier) taken from the
output of a previously located widget opcode (which corresponds to the
target widget). It is used to unequivocally identify the widget when
modifying its appearance with this class of opcodes. The user must not
set the ihandle value directly, otherwise a Csound crash will occur.


===========================================================================
FLsetTextType                                                 *FLsetTextType*

  Description

FLsetTextType sets some attributes related to the fonts of the text
label of the target widget.

  Syntax

FLsetTextType itype, ihandle

  Initialization

itype -- an integer number that modify the appearance of the target widget.

The legal values of itype are:

  * 0 - normal label

  * 1 - no label (hides the text)

  * 2 - symbol label (see below)

  * 3 - shadow label

  * 4 - engraved label

  * 5- embossed label

  * 6- bitmap label (not implemented yet)

  * 7- pixmap label (not implemented yet)

  * 8- image label (not implemented yet)

  * 9- multi label (not implemented yet)

  * 10- free-type label (not implemented yet)

When using itype=3 (symbol label), it is possible to assign a graphical
symbol instead of the text label of the target widget. In this case, the
string of the target label must always start with “@”. If it starts with
something else (or the symbol is not found), the label is drawn
normally. The following symbols are supported:

FLTK label supported symbols.

FLTK label supported symbols.

The @ sign may be followed by the following optional “formatting”
characters, in this order:

 1. “#” forces square scaling rather than distortion to the widget's shape.

 2. +[1-9] or -[1-9] tweaks the scaling a little bigger or smaller.

 3. [1-9] rotates by a multiple of 45 degrees. “6” does nothing, the
    others point in the direction of that key on a numeric keypad.

Notice that with FLbox and FLbutton, it is not necessary to call
FLsetTextType opcode at all in order to use a symbol. In this case, it
is sufficient to set a label starting with “@” followed by the proper
formatting string.

ihandle -- an integer number (used as unique identifier) taken from the
output of a previously located widget opcode (which corresponds to the
target widget). It is used to unequivocally identify the widget when
modifying its appearance with this class of opcodes. The user must not
set the ihandle value directly, otherwise a Csound crash will occur.


===========================================================================
FLsetVal_i                                                       *FLsetVal_i*

  Description

FLsetVal_i forces the value of a valuator to a number provided by the user.

  Syntax

FLsetVal_i ivalue, ihandle

  Initialization

ihandle -- an integer number (used as unique identifier) taken from the
output of a previously located widget opcode (which corresponds to the
target widget). It is used to unequivocally identify the widget when
modifying its appearance with this class of opcodes. The user must not
set the ihandle value directly, otherwise a Csound crash will occur.

  Performance

ivalue -- Value to set the widget to.

  Note
FLsetVal is not fully implemented yet, and may crash in certain cases
(e.g. when setting the value of a widget connected to a FLvalue widget-
in this case use two separate FLsetVal_i).


===========================================================================
FLsetVal                                                           *FLsetVal*

  Description

FLsetVal is almost identical to FLsetVal_i. Except it operates at k-rate
and it affects the target valuator only when ktrig is set to a non-zero
value.

  Syntax

FLsetVal ktrig, kvalue, ihandle

  Initialization

ihandle -- an integer number (used as unique identifier) taken from the
output of a previously located widget opcode (which corresponds to the
target widget). It is used to unequivocally identify the widget when
modifying its appearance with this class of opcodes. The user must not
set the ihandle value directly, otherwise a Csound crash will occur.

  Performance

ktrig -- triggers the opcode when different than 0.

kvalue -- Value to set the widget to.

  Note
FLsetVal is not fully implemented yet, and may crash in certain cases
(e.g. when setting the value of a widget connected to a FLvalue widget-
in this case use two separate FLsetVal)


===========================================================================
FLshow                                                               *FLshow*

  Description

FLshow restores the visibility of a previously hidden widget.

  Syntax

FLshow ihandle

  Initialization

ihandle -- an integer number (used as unique identifier) taken from the
output of a previously located widget opcode (which corresponds to the
target widget). It is used to unequivocally identify the widget when
modifying its appearance with this class of opcodes. The user must not
set the ihandle value directly, otherwise a Csound crash will occur.


===========================================================================
FLslidBnk                                                         *FLslidBnk*

  Description

FLslidBnk is a widget containing a bank of horizontal sliders.

  Syntax

FLslidBnk "names", inumsliders [, ioutable] [, iwidth] [, iheight] [, ix] \
      [, iy] [, itypetable] [, iexptable] [, istart_index] [, iminmaxtable]

  Initialization

“names” -- a double-quoted string containing the names of each slider.
Each slider can have a different name. Separate each name with “@”
character, for example: “frequency@amplitude@cutoff”. It is possible to
not provide any name by giving a single space “”. In this case, the
opcode will automatically assign a progressive number as a label for
each slider.

inumsliders -- the number of sliders.

ioutable (optional, default=0) -- number of a previously-allocated table
in which to store output values of each slider. The user must be sure
that table size is large enough to contain all output cells, otherwise a
segfault will crash Csound. By assigning zero to this argument, the
output will be directed to the zak space in the k-rate zone. In this
case, the zak space must be previously allocated with the zakinit opcode
and the user must be sure that the allocation size is big enough to
cover all sliders. The default value is zero (i.e. store output in zak
space).

istart_index (optional, default=0) -- an integer number referring to a
starting offset of output cell locations. It can be positive to allow
multiple banks of sliders to output in the same table or in the zak
space. The default value is zero (no offset).

iminmaxtable (optional, default=0) -- number of a previously-defined
table containing a list of min-max pairs, referred to each slider. A
zero value defaults to the 0 to 1 range for all sliders without
necessity to provide a table. The default value is zero.

iexptable (optional, default=0) -- number of a previously-defined table
containing a list of identifiers (i.e. integer numbers) provided to
modify the behaviour of each slider independently. Identifiers can
assume the following values:

  * -1 -- exponential curve response

  * 0 -- linear response

  * number > than 0 -- follow the curve of a previously-defined table to
    shape the response of the corresponding slider. In this case, the
    number corresponds to table number.

You can assume that all sliders of the bank have the same response curve
(exponential or linear). In this case, you can assign -1 or 0 to
iexptable without worrying about previously defining any table. The
default value is zero (all sliders have a linear response, without
having to provide a table).

itypetable (optional, default=0) -- number of a previously-defined table
containing a list of identifiers (i.e. integer numbers) provided to
modify the aspect of each individual slider independently. Identifiers
can assume the following values:

  * 0 = Nice slider

  * 1 = Fill slider

  * 3 = Normal slider

  * 5 = Nice slider

  * 7 = Nice slider with down-box

You can assume that all sliders of the bank have the same aspect. In
this case, you can assign a negative number to itypetable without
worrying about previously defining any table. Negative numbers have the
same meaning of the corresponding positive identifiers with the
difference that the same aspect is assigned to all sliders. You can also
assign a random aspect to each slider by setting itypetable to a
negative number lower than -7. The default value is zero (all sliders
have the aspect of nice sliders, without having to provide a table).

You can add 20 to a value inside the table to make the slider "plastic",
or subtract 20 if you want to set the value for all widgets without
defining a table (e.g. -21 to set all sliders types to Plastic Fill
slider).

iwidth (optional) -- width of the rectangular area containing all
sliders of the bank, excluding text labels, that are placed to the left
of that area.

iheight (optional) -- height of the rectangular area containing all
sliders of the bank, excluding text labels, that are placed to the left
of that area.

ix (optional) -- horizontal position of the upper left corner of the
rectangular area containing all sliders belonging to the bank. You have
to leave enough space, at the left of that rectangle, in order to make
sure labels of sliders to be visible. This is because the labels
themselves are external to the rectangular area.

iy (optional) -- vertical position of the upper left corner of the
rectangular area containing all sliders belonging to the bank. You have
to leave enough space, at the left of that rectangle, in order to make
sure labels of sliders to be visible. This is because the labels
themselves are external to the rectangular area.

  Performance

There are no k-rate arguments, even if cells of the output table (or the
zak space) are updated at k-rate.

FLslidBnk is a widget containing a bank of horizontal sliders. Any
number of sliders can be placed into the bank (inumsliders argument).
The output of all sliders is stored into a previously allocated table or
into the zak space (ioutable argument). It is possible to determine the
first location of the table (or of the zak space) in which to store the
output of the first slider by means of istart_index argument.

Each slider can have an individual label that is placed to the left of
it. Labels are defined by the “names” argument. The output range of each
slider can be individually set by means of an external table
(iminmaxtable argument). The curve response of each slider can be set
individually, by means of a list of identifiers placed in a table
(iexptable argument). It is possible to define the aspect of each slider
independently or to make all sliders have the same aspect (itypetable
argument).

The iwidth, iheight, ix, and iy arguments determine width, height,
horizontal and vertical position of the rectangular area containing
sliders. Notice that the label of each slider is placed to the left of
them and is not included in the rectangular area containing sliders. So
the user should leave enough space to the left of the bank by assigning
a proper ix value in order to leave labels visible.

  IMPORTANT!

Notice that the tables used by FLslidBnk must be created with the ftgen
opcode and placed in the orchestra before the corresponding valuator.
They can not placed in the score. This is because tables placed in the
score are created later than the initialization of the opcodes placed in
the header section of the orchestra.


===========================================================================
FLslidBnk2                                                       *FLslidBnk2*

  Description

FLslidBnk2 is a widget containing a bank of horizontal sliders.

  Syntax

FLslidBnk2 "names", inumsliders, ioutable, iconfigtable [,iwidth, iheight, ix, iy, istart_index] 

  Initialization

“names” -- a double-quoted string containing the names of each slider.
Each slider can have a different name. Separate each name with “@”
character, for example: “frequency@amplitude@cutoff”. It is possible to
not provide any name by giving a single space “”. In this case, the
opcode will automatically assign a progressive number as a label for
each slider.

inumsliders -- the number of sliders.

ioutable (optional, default=0) -- number of a previously-allocated table
in which to store output values of each slider. The user must be sure
that table size is large enough to contain all output cells, otherwise a
segfault will crash Csound. By assigning zero to this argument, the
output will be directed to the zak space in the k-rate zone. In this
case, the zak space must be previously allocated with the zakinit opcode
and the user must be sure that the allocation size is big enough to
cover all sliders. The default value is zero (i.e. store output in zak
space).

iconfigtable -- in the FLslidBnk2 and FLvslidBnk2 opcodes, this table
replaces iminmaxtable, iexptable and istyletable, all these parameters
being placed into a single table. This table has to be filled with a
group of 4 parameters for each slider in this way:

min1, max1, exp1, style1, min2, max2, exp2, style2, min3, max3, exp3, style3 etc.

for example using GEN02 you can type:

inum ftgen 1,0,256, -2,     0,1,0,1,    100, 5000, -1, 3,      50, 200, -1, 5,….. [etcetera]

In this example the first slider will be affected by the [0,1,0,1]
parameters (the range will be 0 to 1, it will have linear response, and
its aspect will be a fill slider), the second slider will be affected by
the [100,5000,-1,3] parameters (the range is 100 to 5000, the response
is exponential and the aspect is a normal slider), the third slider will
be affected by the [50,200,-1,5] parameters (the range is 50 to 200, the
behavior exponential, and the aspect is a nice slider), and so on.

iwidth (optional) -- width of the rectangular area containing all
sliders of the bank, excluding text labels, that are placed to the left
of that area.

iheight (optional) -- height of the rectangular area containing all
sliders of the bank, excluding text labels, that are placed to the left
of that area.

ix (optional) -- horizontal position of the upper left corner of the
rectangular area containing all sliders belonging to the bank. You have
to leave enough space, at the left of that rectangle, in order to make
sure labels of sliders to be visible. This is because the labels
themselves are external to the rectangular area.

iy (optional) -- vertical position of the upper left corner of the
rectangular area containing all sliders belonging to the bank. You have
to leave enough space, at the left of that rectangle, in order to make
sure labels of sliders to be visible. This is because the labels
themselves are external to the rectangular area.

istart_index (optional, default=0) -- an integer number referring to a
starting offset of output cell locations. It can be positive to allow
multiple banks of sliders to output in the same table or in the zak
space. The default value is zero (no offset).

  Performance

There are no k-rate arguments, even if cells of the output table (or the
zak space) are updated at k-rate.

FLslidBnk2 is a widget containing a bank of horizontal sliders. Any
number of sliders can be placed into the bank (inumsliders argument).
The output of all sliders is stored into a previously allocated table or
into the zak space (ioutable argument). It is possible to determine the
first location of the table (or of the zak space) in which to store the
output of the first slider by means of istart_index argument.

Each slider can have an individual label that is placed to the left of
it. Labels are defined by the “names” argument. The output range of each
slider can be individually set by means of the min and max values inside
the iconfigtable table. The curve response of each slider can be set
individually, by means of a list of identifiers placed in the
iconfigtable table (exp argument). It is possible to define the aspect
of each slider independently or to make all sliders have the same aspect
(style argument in the iconfigtable table).

The iwidth, iheight, ix, and iy arguments determine width, height,
horizontal and vertical position of the rectangular area containing
sliders. Notice that the label of each slider is placed to the left of
them and is not included in the rectangular area containing sliders. So
the user should leave enough space to the left of the bank by assigning
a proper ix value in order to leave labels visible.

  IMPORTANT!

Notice that the tables used by FLslidBnk2 must be created with the ftgen
opcode and placed in the orchestra before the corresponding valuator.
They can not placed in the score. This is because tables placed in the
score are created later than the initialization of the opcodes placed in
the header section of the orchestra.


===========================================================================
FLslidBnkGetHandle                                       *FLslidBnkGetHandle*

  Description

FLslidBnkGetHandle gets the handle of last slider bank created.

  Syntax

ihandle FLslidBnkGetHandle

  Initialization

ihandle - handle of the sliderBnk (to be used to set its values).

  Performance

There are no k-rate arguments, even if cells of the output table (or the
zak space) are updated at k-rate.

FLslidBnkGetHandle gets the handle of last slider bank created. This
opcode must follow corresponding FLslidBnk (or FLvslidBnk, FLslidBnk2
and FLvslidBnk2) immediately, in order to get its handle.

See the entry for FLslidBnk2Setk to see an example of usage.


===========================================================================
FLslidBnkSet                                                   *FLslidBnkSet*

  Description

FLslidBnkSet modifies the values of a slider bank according to an array
of values stored in a table.

  Syntax

FLslidBnkSet ihandle, ifn [, istartIndex, istartSlid, inumSlid]

  Initialization

ihandle - handle of the sliderBnk (to be used to set its values).

ifn - number of a table containing an array of values to set each slider
to.

istartIndex - (optional) starting index of the table element of to be
evaluated firstly. Default value is zero

istartSlid - (optional) starting slider to be evaluated. Default 0,
denoting the first slider.

inumSlid - (optional) number of sliders to be updated. Default 0,
denoting all sliders.

  Performance

FLslidBnkSet modifies the values of a slider bank (created with
FLslidBnk or with FLvslidBnk) according to an array of values stored
into table ifn. It actually allows to update an FLslidBnk (or
FLvslidBnk) bank of sliders (for instance, using the slider8table
opcode) to a set of values located in a table. User has to set ihandle
argument to the handle got from FLslidBnkGetHandle opcode. It works at
init-rate only. It is possible to reset only a range of sliders, by
using the optional arguments istartIndex, istartSlid, inumSlid

There is a k-rate version of this opcode called FLslidBnkSetk.


===========================================================================
FLslidBnkSetk                                                 *FLslidBnkSetk*

  Description

FLslidBnkSetk modifies the values of a slider bank according to an array
of values stored in a table.

  Syntax

FLslidBnkSetk  ktrig, ihandle, ifn [, istartIndex, istartSlid, inumSlid]

  Initialization

ihandle - handle of the sliderBnk (to be used to set its values).

ifn - number of a table containing an array of values to set each slider
to.

istartIndex - (optional) starting index of the table element of to be
evaluated firstly. Default value is zero

istartSlid - (optional) starting slider to be evaluated. Default 0,
denoting the first slider.

inumSlid - (optional) number of sliders to be updated. Default 0,
denoting all sliders.

  Performance

ktrig – the output of FLslidBnkSetk consists of a trigger that informs
if sliders have to be updated or not. A non-zero value forces the slider
to be updated.

FLslidBnkSetk is similar to FLslidBnkSet but allows k-rate to modify the
values of FLslidBnk (FLslidBnkSetk can also be used with FLvslidBnk,
obtaining identical result). It also allows the slider bank to be joined
with MIDI. If you are using MIDI (for instance, when using the
slider8table opcode), FLslidBnkSetk changes the values of FLslidBnk bank
of sliders to a set of values located in a table. This opcode is
actually able to serve as a MIDI bridge to the FLslidBnk widget when
used together with the sliderXXtable set of opcodes (see slider8table
entry for more information). Notice, that, when you want to use table
indexing as a curve response, it is not possible to do it directly in
the iconfigtable configuration of FLslidBnk2, when you intend to use the
FLslidBnkSetk opcode. In fact, corresponding inputTable element of
FLslidBnkSetk must be set in linear mode and respect the 0 to 1 range.
Even the corresponding elements of sliderXXtable must be set in linear
mode and in the normalized range. You can do table indexing later, by
using the tab and tb opcodes, and rescaling output according to max and
min values. By the other hand, it is possible to use linear and
exponential curve response directly, by setting the actual min-max range
and flag both in the iconfigtable of corresponding FLslidBnk2 and in
sliderXXtable.

FLslidBnkSetk the k-rate version of FLslidBnk2Set.


===========================================================================
FLslidBnk2Set                                                 *FLslidBnk2Set*

  Description

FLslidBnk2Set modifies the values of a slider bank according to an array
of values stored in a table.

  Syntax

FLslidBnk2Set ihandle, ifn [, istartIndex, istartSlid, inumSlid]

  Initialization

ihandle - handle of the sliderBnk (to be used to set its values).

ifn - number of a table containing an array of values to set each slider
to.

istartIndex - (optional) starting index of the table element of to be
evaluated firstly. Default value is zero

istartSlid - (optional) starting slider to be evaluated. Default 0,
denoting the first slider.

inumSlid - (optional) number of sliders to be updated. Default 0,
denoting all sliders.

  Performance

FLslidBnk2Set modifies the values of a slider bank (created with
FLslidBnk2 or with FLvslidBnk2) according to an array of values stored
into table ifn. It actually allows to update an FLslidBnk2 (or
FLvslidBnk2) bank of sliders (for instance, using the slider8table
opcode) to a set of values located in a table. User has to set ihandle
argument to the handle got from FLslidBnkGetHandle opcode. It works at
init-rate only. It is possible to reset only a range of sliders, by
using the optional arguments istartIndex, istartSlid, inumSlid

FLslidBnk2Set is identical to FLslidBnkSet, but works on FLslidBnk2 and
FLvslidBnk2 instead of FLslidBnk and FLvslidBnk.

There is a k-rate version of this opcode called FLslidBnk2Setk.


===========================================================================
FLslidBnk2Setk                                               *FLslidBnk2Setk*

  Description

FLslidBnk2Setk modifies the values of a slider bank according to an
array of values stored in a table.

  Syntax

FLslidBnk2Setk  ktrig, ihandle, ifn [, istartIndex, istartSlid, inumSlid]

  Initialization

ihandle - handle of the sliderBnk (to be used to set its values).

ifn - number of a table containing an array of values to set each slider
to.

istartIndex - (optional) starting index of the table element of to be
evaluated firstly. Default value is zero

istartSlid - (optional) starting slider to be evaluated. Default 0,
denoting the first slider.

inumSlid - (optional) number of sliders to be updated. Default 0,
denoting all sliders.

  Performance

ktrig – the output of FLslidBnk2Setk consists of a trigger that informs
if sliders have to be updated or not. A non-zero value forces the slider
to be updated.

FLslidBnk2Setk is similar to FLslidBnkSet but allows k-rate to modify
the values of FLslidBnk2 (FLslidBnk2Setk can also be used with
FLvslidBnk2, obtaining identical result). It also allows the slider bank
to be joined with MIDI. If you are using MIDI (for instance, when using
the slider8table opcode), FLslidBnk2Setk changes the values of
FLslidBnk2 bank of sliders to a set of values located in a table. This
opcode is actually able to serve as a MIDI bridge to the FLslidBnk2
widget when used together with the sliderXXtable set of opcodes (see
slider8table entry for more information). Notice, that, when you want to
use table indexing as a curve response, it is not possible to do it
directly in the iconfigtable configuration of FLslidBnk2, when you
intend to use the FLslidBnk2Setk opcode. In fact, corresponding
inputTable element of FLslidBnk2Setk must be set in linear mode and
respect the 0 to 1 range. Even the corresponding elements of
sliderXXtable must be set in linear mode and in the normalized range.
You can do table indexing later, by using the tab and tb opcodes, and
rescaling output according to max and min values. By the other hand, it
is possible to use linear and exponential curve response directly, by
setting the actual min-max range and flag both in the iconfigtable of
corresponding FLslidBnk2 and in sliderXXtable.

FLslidBnk2Setk the k-rate version of FLslidBnk2Set.


===========================================================================
FLslider                                                           *FLslider*

  Description

FLslider puts a slider into the corresponding container.

  Syntax

kout, ihandle FLslider "label", imin, imax, iexp, itype, idisp, iwidth, \
      iheight, ix, iy

  Initialization

ihandle -- a handle value (an integer number) that unequivocally
references a corresponding widget. This is used by other opcodes that
modify a widget's properties (see Modifying FLTK Widget Appearance). It
is automatically output by FLslider and must not be set by the user
label. (The user label is a double-quoted string containing some
user-provided text placed near the widget.)

“label” -- a double-quoted string containing some user-provided text,
placed near the corresponding widget.

imin -- minimum value of output range (corresponds to the left value for
horizontal sliders, and the top value for vertical sliders).

imax -- maximum value of output range (corresponds to the right value
for horizontal sliders, and the bottom value for vertical sliders).

The imin argument may be greater than imax argument. This has the effect
of “reversing” the object so the larger values are in the opposite
direction. This also switches which end of the filled sliders is filled.

iexp -- an integer number denoting the behaviour of valuator:

  * 0 = valuator output is linear

  * -1 = valuator output is exponential

All other positive numbers for iexp indicate the number of an existing
table that is used for indexing. Linear interpolation is provided in
table indexing. A negative table number suppresses interpolation.

  IMPORTANT!

Notice that the tables used by valuators must be created with the ftgen
opcode and placed in the orchestra before the corresponding valuator.
They can not placed in the score. This is because tables placed in the
score are created later than the initialization of the opcodes placed in
the header section of the orchestra.

itype -- an integer number denoting the appearance of the valuator.

The itype argument can be set to the following values:

  * 1 - shows a horizontal fill slider

  * 2 - a vertical fill slider

  * 3 - a horizontal engraved slider

  * 4 - a vertical engraved slider

  * 5 - a horizontal nice slider

  * 6 - a vertical nice slider

  * 7 - a horizontal up-box nice slider

  * 8 - a vertical up-box nice slider

FLslider - a horizontal fill slider (itype=1).

FLslider - a horizontal fill slider (itype=1).

FLslider - a horizontal engraved slider (itype=3).

FLslider - a horizontal engraved slider (itype=3).

FLslider - a horizontal nice slider (itype=5).

FLslider - a horizontal nice slider (itype=5).

You can also create "plastic" looking sliders by adding 20 to itype.

idisp -- a handle value that was output from a previous instance of the
FLvalue opcode to display the current value of the current valuator in
the FLvalue widget itself. If the user doesn't want to use this feature
that displays current values, it must be set to a negative number by the
user.

iwidth -- width of widget.

iheight -- height of widget.

ix -- horizontal position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

iy -- vertical position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

  Performance

kout -- output value

FLsliders are created with the minimum value by default in the left/at
the top. If you want to reverse the slider, reverse the values. See the
example below.


===========================================================================
FLtabs                                                               *FLtabs*

  Description

FLtabs is a “file card tabs” interface that is useful to display several
areas containing widgets in the same windows, alternatively. It must be
used together with FLgroup, another container that groups child widgets.

  Syntax

FLtabs iwidth, iheight, ix, iy

  Initialization

iwidth -- width of widget.

iheight -- height of widget.

ix -- horizontal position of upper left corner of the valuator, relative
to the upper left corner of corresponding window. Expressed in pixels.

iy -- vertical position of upper left corner of the valuator, relative
to the upper left corner of corresponding window. Expressed in pixels.

  Performance

Containers are useful to format the graphic appearance of the widgets.
The most important container is FLpanel, that actually creates a window.
It can be filled with other containers and/or valuators or other kinds
of widgets.

There are no k-rate arguments in containers.

FLtabs is a “file card tabs” interface that is useful to display several
alternate areas containing widgets in the same window.

FLtabs.

FLtabs.

It must be used together with FLgroup, another FLTK container opcode
that groups child widgets.


===========================================================================
FLtabsEnd                                                         *FLtabsEnd*

  Description

Marks the end of a tabbed FLTK interface.

  Syntax

FLtabsEnd

  Performance

Containers are useful to format the graphic appearance of the widgets.
The most important container is FLpanel, that actually creates a window.
It can be filled with other containers and/or valuators or other kinds
of widgets.

There are no k-rate arguments in containers.


===========================================================================
FLtabs_end                                                       *FLtabs_end*

  Description

Marks the end of a tabbed FLTK interface. This is another name for
FLtabsEnd provided for compatibility. See FLtabsEnd


===========================================================================
FLtext                                                               *FLtext*

  Description

FLtext allows the user to modify a parameter value by directly typing it
into a text field.

  Syntax

kout, ihandle FLtext "label", imin, imax, istep, itype, iwidth, \
      iheight, ix, iy

  Initialization

ihandle -- a handle value (an integer number) that unequivocally
references a corresponding widget. This is used by other opcodes that
modify a widget's properties (see Modifying FLTK Widget Appearance). It
is automatically output by FLtext and must not be set by the user label.
(The user label is a double-quoted string containing some user-provided
text placed near the widget.)

“label” -- a double-quoted string containing some user-provided text,
placed near corresponding widget.

imin -- minimum value of output range.

imax -- maximum value of output range.

istep -- a floating-point number indicating the increment of valuator
value corresponding to the mouse dragging. The istep argument allows the
user to arbitrarily slow mouse motion, enabling arbitrary precision.

itype -- an integer number denoting the appearance of the valuator.

The itype argument can be set to the following values:

  * 1 - normal behaviour

  * 2 - dragging operation is suppressed, instead it will appear two
    arrow buttons. A mouse-click on one of these buttons can
    increase/decrease the output value.

  * 3 - text editing is suppressed, only mouse dragging modifies the
    output value.

iwidth -- width of widget.

iheight -- height of widget.

ix -- horizontal position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

iy -- vertical position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

  Performance

kout -- output value

FLtext allows the user to modify a parameter value by directly typing it
into a text field:

FLtext.

FLtext.

Its value can also be modified by clicking on it and dragging the mouse
horizontally. The istep argument allows the user to arbitrarily set the
response on mouse dragging.


===========================================================================
FLupdate                                                           *FLupdate*

  Description

Same as the FLrun opcode.

  Syntax

FLupdate

===========================================================================
fluidAllOut                                                     *fluidAllOut*

  Syntax

aleft, aright fluidAllOut

  Description

Collects all audio from all Fluidsynth engines in a performance

  Performance

aleft -- Left channel audio output.

aright -- Right channel audio output.

Invoke fluidAllOut in an instrument definition numbered higher than any
fluidcontrol instrument definitions. All SoundFonts send their audio
output to this one opcode. Send a note with an indefinite duration to
this instrument to turn the SoundFonts on for as long as required.

In this implementation, SoundFont effects such as chorus or reverb are
used if and only if they are defaults for the preset. There is no means
of turning such effects on or off, or of changing their parameters, from
Csound.


===========================================================================
fluidCCi                                                           *fluidCCi*

  Syntax

fluidCCi iEngineNumber, iChannelNumber, iControllerNumber, iValue

  Description

Sends a MIDI controller data (MIDI controller number and value to use)
message to a fluid engine by number on the user specified MIDI channel
number.

  Initialization

iEngineNumber -- engine number assigned from fluidEngine

iChannelNumber -- MIDI channel number to which the Fluidsynth program is
assigned: from 0 to 255. MIDI channels numbered 16 or higher are virtual
channels.

iControllerNumber -- MIDI controller number to use for this message

iValue -- value to set for controller (usually 0-127)

  Performance

This opcode is useful for setting controller values at init time. For
continous changes, use fluidCCk.


===========================================================================
fluidCCk                                                           *fluidCCk*

  Syntax

fluidCCk iEngineNumber, iChannelNumber, iControllerNumber, kValue

  Description

Sends a MIDI controller data (MIDI controller number and value to use)
message to a fluid engine by number on the user specified MIDI channel
number.

  Initialization

iEngineNumber -- engine number assigned from fluidEngine

iChannelNumber -- MIDI channel number to which the Fluidsynth program is
assigned: from 0 to 255. MIDI channels numbered 16 or higher are virtual
channels.

iControllerNumber -- MIDI controller number to use for this message

  Performance

kValue -- value to set for controller (usually 0-127)


===========================================================================
fluidControl                                                   *fluidControl*

  Syntax

fluidControl ienginenum, kstatus, kchannel, kdata1, kdata2

  Description

The fluid opcodes provide a simple Csound opcode wrapper around Peter
Hanappe's Fluidsynth SoundFont2 synthesizer. This implementation accepts
any MIDI note on, note off, controller, pitch bend, or program change
message at k-rate. Maximum polyphony is 4096 simultaneously sounding
voices. Any number of SoundFonts may be loaded and played simultaneously.

  Initialization

ienginenum -- engine number assigned from fluidEngine

  Performance

kstatus -- MIDI channel message status byte: 128 for note off, 144 for
note on, 176 for control change, 192 for program change, or 224 for
pitch bend.

kchannel -- MIDI channel number to which the Fluidsynth program is
assigned: from 0 to 255. MIDI channels numbered 16 or higher are virtual
channels.

kdata1 -- For note on, MIDI key number: from 0 (lowest) to 127
(highest), where 60 is middle C. For continuous controller messages,
controller number.

kdata2 -- For note on, MIDI key velocity: from 0 (no sound) to 127
(loudest). For continous controller messages, controller value.

Invoke fluidControl in instrument definitions that actually play notes
and send control messages. Each instrument definition must consistently
use one MIDI channel that was assigned to a Fluidsynth program using
fluidLoad.

In this implementation, SoundFont effects such as chorus or reverb are
used if and only if they are defaults for the preset. There is no means
of turning such effects on or off, or of changing their parameters, from
Csound.


===========================================================================
fluidEngine                                                     *fluidEngine*

  Syntax

ienginenum fluidEngine [iReverbEnabled] [, iChorusEnabled] [,iNumChannels] [, iPolyphony] 

  Description

Instantiates a fluidsynth engine, and returns ienginenum to identify the
engine. ienginenum is passed to other other opcodes for loading and
playing SoundFonts and gathering the generated sound.

  Initialization

ienginenum -- engine number assigned from fluidEngine.

iReverbEnabled -- optionally set to 0 to disable any reverb effect in
the loaded SoundFonts.

iChorusEnabled -- optionally set to 0 to disable any chorus effect in
the loaded SoundFonts.

iNumChannels -- number of channels to use; range is 16-256 and Csound
default is 256 (Fluidsynth's default is 16).

iPolyphony -- number of voices to be played in parallel; range is
16-4096 and Csound default is 4096 (Fluidsynth's default is 256). Note:
this is not the number of notes played at the same time as a single note
may use create multiple voices depending on instrument zones and
velocity/key of played note.


===========================================================================
fluidLoad                                                         *fluidLoad*

  Syntax

isfnum fluidLoad soundfont, ienginenum[, ilistpresets]

  Description

Loads a SoundFont into an instance of a fluidEngine, optionally listing
banks and presets for SoundFont.

  Initialization

isfnum -- number assigned to just-loaded soundfont.

soundfont -- string specifying a SoundFont filename. Note that any
number of SoundFonts may be loaded (obviously, by different invocations
of fluidLoad).

ienginenum -- engine number assigned from fluidEngine

ilistpresets -- optional, if specified, lists all Fluidsynth programs
for the just-loaded SoundFont. A Fluidsynth program is a combination of
SoundFont ID, bank number, and preset number that is assigned to a MIDI
channel.

  Performance

Invoke fluidLoad in the orchestra header, any number of times. The same
SoundFont may be invoked to assign programs to MIDI channels any number
of times; the SoundFont is only loaded the first time.


===========================================================================
fluidNote                                                         *fluidNote*

  Syntax

fluidNote ienginenum, ichannelnum, imidikey, imidivel

  Description

Plays a note at imidikey pitch and imidivel velocity on ichannelnum
channel of number ienginenum fluidEngine.

  Initialization

ienginenum -- engine number assigned from fluidEngine

ichannelnum -- which channel number to play a note on in the given
fluidEngine

imidikey -- MIDI key for note (0-127)

imidivel -- MIDI velocity for note (0-127)


===========================================================================
fluidOut                                                           *fluidOut*

  Syntax

aleft, aright fluidOut ienginenum

  Description

Outputs the sound from a fluidEngine.

  Initialization

ienginenum -- engine number assigned from fluidEngine

  Performance

aleft -- Left channel audio output.

aright -- Right channel audio output.

Invoke fluidOut in an instrument definition numbered higher than any
fluidcontrol instrument definitions. All SoundFonts used in the
fluidEngine numbered ienginenum send their audio output to this one
opcode. Send a note with an indefinite duration to this instrument to
turn the SoundFonts on for as long as required.


===========================================================================
fluidProgramSelect                                       *fluidProgramSelect*

  Syntax

fluidProgramSelect ienginenum, ichannelnum, isfnum, ibanknum, ipresetnum

  Description

Assigns a preset from a SoundFont to a channel on a fluidEngine.

  Initialization

ienginenum -- engine number assigned from fluidEngine

ichannelnum -- which channel number to use for the preset in the given
fluidEngine

isfnum -- number of the SoundFont from which the preset is assigned

ibanknum -- number of the bank in the SoundFont from which the preset is
assigned

ipresetnum -- number of the preset to assign


===========================================================================
fluidSetInterpMethod                                   *fluidSetInterpMethod*

  Syntax

fluidSetInterpMethod ienginenum, ichannelnum, iInterpMethod

  Description

Set interpolation method for channel in Fluid Engine. Lower order
interpolation methods will render faster at lower fidelity while higher
order interpolation methods will render slower at higher fidelity.
Default interpolation for a channel is 4th order interpolation.

  Initialization

ienginenum -- engine number assigned from fluidEngine

ichannelnum -- which channel number to use for the preset in the given
fluidEngine

iInterpMethod -- interpolation method, can be any of the following

  * 0 -- No Interpolation

  * 1 -- Linear Interpolation

  * 4 -- 4th Order Interpolation (Default)

  * 7 -- 7th Order Interpolation (Highest)


===========================================================================
FLvalue                                                             *FLvalue*

  Description

FLvalue shows current the value of a valuator in a text field.

  Syntax

ihandle FLvalue "label", iwidth, iheight, ix, iy

  Initialization

ihandle -- handle value (an integer number) that unequivocally
references the corresponding valuator. It can be used for the idisp
argument of a valuator.

“label” -- a double-quoted string containing some user-provided text,
placed near the corresponding widget.

iwidth -- width of widget.

iheight -- height of widget.

ix -- horizontal position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

iy -- vertical position of upper left corner of the valuator, relative
to the upper left corner of corresponding window (expressed in pixels).

  Performance

FLvalue shows the current values of a valuator in a text field. It
outputs ihandle that can then be used for the idisp argument of a
valuator (see the FLTK Valuators section). In this way, the values of
that valuator will be dynamically be shown in a text field.

  Note

Note that FLvalue is not a valuator and its value cannot be modified.The
value for an FLvalue widget should be set only by other widgets, and NOT
from FLsetVal or FLsetVal_i since this can cause Csound to crash.


===========================================================================
FLvkeybd                                                           *FLvkeybd*

  Description

An FLTK widget opcode that creates a virtual keyboard widget. This must
be used in conjunction with the virtual midi keyboard driver for this to
operate correctly. The purpose of this opcode is for making demo
versions of MIDI orchestras with the virtual keyboard embedded within
the main window.

  Note

The widget version of the virtual keyboard does not include the MIDI
sliders found in the full window version of the virtual keyboard.

  Syntax

FLvkeybd "keyboard.map", iwidth, iheight, ix, iy

  Initialization

“keyboard.map” -- a double-quoted string containing the keyboard map to
use. An empty string ("") may be used to use the default bank/channel
name values. See Virtual Midi Keyboard for more information on keyboard
mappings.

iwidth -- width of widget.

iheight -- height of widget.

ix -- horizontal position of upper left corner of the keyboard, relative
to the upper left corner of corresponding window (expressed in pixels).

iy -- vertical position of upper left corner of the keyboard, relative
to the upper left corner of corresponding window (expressed in pixels).

  Note

The standard width and height for the virtual keyboard is 624x120 for
the dialog version that is shown when FLvkeybd is not used.


===========================================================================
FLvslidBnk                                                       *FLvslidBnk*

  Description

FLvslidBnk is a widget containing a bank of vertical sliders.

  Syntax

FLvslidBnk "names", inumsliders [, ioutable] [, iwidth] [, iheight] [, ix] \
      [, iy] [, itypetable] [, iexptable] [, istart_index] [, iminmaxtable]

  Initialization

“names” -- a double-quoted string containing the names of each slider.
Each slider can have a different name. Separate each name with “@”
character, for example: “frequency@amplitude@cutoff”. It is possible to
not provide any name by giving a single space “”. In this case, the
opcode will automatically assign a progressive number as a label for
each slider.

inumsliders -- the number of sliders.

ioutable (optional, default=0) -- number of a previously-allocated table
in which to store output values of each slider. The user must be sure
that table size is large enough to contain all output cells, otherwise a
segfault will crash Csound. By assigning zero to this argument, the
output will be directed to the zak space in the k-rate zone. In this
case, the zak space must be previously allocated with the zakinit opcode
and the user must be sure that the allocation size is big enough to
cover all sliders. The default value is zero (i.e. store output in zak
space).

istart_index (optional, default=0) -- an integer number referring to a
starting offset of output cell locations. It can be positive to allow
multiple banks of sliders to output in the same table or in the zak
space. The default value is zero (no offset).

iminmaxtable (optional, default=0) -- number of a previously-defined
table containing a list of min-max pairs, referred to each slider. A
zero value defaults to the 0 to 1 range for all sliders without
necessity to provide a table. The default value is zero.

iexptable (optional, default=0) -- number of a previously-defined table
containing a list of identifiers (i.e. integer numbers) provided to
modify the behaviour of each slider independently. Identifiers can
assume the following values:

  * -1 -- exponential curve response

  * 0 -- linear response

  * number > than 0 -- follow the curve of a previously-defined table to
    shape the response of the corresponding slider. In this case, the
    number corresponds to table number.

You can assume that all sliders of the bank have the same response curve
(exponential or linear). In this case, you can assign -1 or 0 to
iexptable without worrying about previously defining any table. The
default value is zero (all sliders have a linear response, without
having to provide a table).

itypetable (optional, default=0) -- number of a previously-defined table
containing a list of identifiers (i.e. integer numbers) provided to
modify the aspect of each individual slider independently. Identifiers
can assume the following values:

  * 0 = Nice slider

  * 1 = Fill slider

  * 3 = Normal slider

  * 5 = Nice slider

  * 7 = Nice slider with down-box

You can assume that all sliders of the bank have the same aspect. In
this case, you can assign a negative number to itypetable without
worrying about previously defining any table. Negative numbers have the
same meaning of the corresponding positive identifiers with the
difference that the same aspect is assigned to all sliders. You can also
assign a random aspect to each slider by setting itypetable to a
negative number lower than -7. The default value is zero (all sliders
have the aspect of nice sliders, without having to provide a table).

You can add 20 to a value inside the table to make the slider "plastic",
or subtract 20 if you want to set the value for all widgets without
defining a table (e.g. -21 to set all sliders types to Plastic Fill
slider).

iwidth (optional) -- width of the rectangular area containing all
sliders of the bank, excluding text labels, that are placed below that
area.

iheight (optional) -- height of the rectangular area containing all
sliders of the bank, excluding text labels, that are placed below that
area.

ix (optional) -- horizontal position of the upper left corner of the
rectangular area containing all sliders belonging to the bank. You have
to leave enough space, below that rectangle, in order to make sure
labels of sliders to be visible. This is because the labels themselves
are external to the rectangular area.

iy (optional) -- vertical position of the upper left corner of the
rectangular area containing all sliders belonging to the bank. You have
to leave enough space, below that rectangle, in order to make sure
labels of sliders to be visible. This is because the labels themselves
are external to the rectangular area.

  Performance

There are no k-rate arguments, even if cells of the output table (or the
zak space) are updated at k-rate.

FLvslidBnk is a widget containing a bank of vertical sliders. Any number
of sliders can be placed into the bank (inumsliders argument). The
output of all sliders is stored into a previously allocated table or
into the zak space (ioutable argument). It is possible to determine the
first location of the table (or of the zak space) in which to store the
output of the first slider by means of istart_index argument.

Each slider can have an individual label that is placed below it. Labels
are defined by the “names” argument. The output range of each slider can
be individually set by means of an external table (iminmaxtable
argument). The curve response of each slider can be set individually, by
means of a list of identifiers placed in a table (iexptable argument).
It is possible to define the aspect of each slider independently or to
make all sliders have the same aspect (itypetable argument).

The iwidth, iheight, ix, and iy arguments determine width, height,
horizontal and vertical position of the rectangular area containing
sliders. Notice that the label of each slider is placed below them and
is not included in the rectangular area containing sliders. So the user
should leave enough space below the bank by assigning a proper iy value
in order to leave labels visible.

FLvslidBnk is identical to FLslidBnk except it contains vertical sliders
instead of horizontal. Since the width of each single slider is often
small, it is recommended to leave only a single space in the names
string (“ “), in this case each slider will be automatically numbered.

  IMPORTANT!

Notice that the tables used by FLvslidBnk must be created with the ftgen
opcode and placed in the orchestra before the corresponding valuator.
They can not placed in the score. This is because tables placed in the
score are created later than the initialization of the opcodes placed in
the header section of the orchestra.


===========================================================================
FLvslidBnk2                                                     *FLvslidBnk2*

  Description

FLvslidBnk2 is a widget containing a bank of vertical sliders.

  Syntax

FLvslidBnk2 "names", inumsliders, ioutable, iconfigtable [,iwidth, iheight, ix, iy, istart_index]

  Initialization

“names” -- a double-quoted string containing the names of each slider.
Each slider can have a different name. Separate each name with “@”
character, for example: “frequency@amplitude@cutoff”. It is possible to
not provide any name by giving a single space “”. In this case, the
opcode will automatically assign a progressive number as a label for
each slider.

inumsliders -- the number of sliders.

ioutable (optional, default=0) -- number of a previously-allocated table
in which to store output values of each slider. The user must be sure
that table size is large enough to contain all output cells, otherwise a
segfault will crash Csound. By assigning zero to this argument, the
output will be directed to the zak space in the k-rate zone. In this
case, the zak space must be previously allocated with the zakinit opcode
and the user must be sure that the allocation size is big enough to
cover all sliders. The default value is zero (i.e. store output in zak
space).

iconfigtable -- in the FLslidBnk2 and FLvslidBnk2 opcodes, this table
replaces iminmaxtable, iexptable and istyletable, all these parameters
being placed into a single table. This table has to be filled with a
group of 4 parameters for each slider in this way:

min1, max1, exp1, style1, min2, max2, exp2, style2, min3, max3, exp3, style3 etc.

for example using GEN02 you can type:

inum ftgen 1,0,256, -2,     0,1,0,1,    100, 5000, -1, 3,      50, 200, -1, 5,….. [etcetera]

In this example the first slider will be affected by the [0,1,0,1]
parameters (the range will be 0 to 1, it will have linear response, and
its aspect will be a fill slider), the second slider will be affected by
the [100,5000,-1,3] parameters (the range is 100 to 5000, the response
is exponential and the aspect is a normal slider), the third slider will
be affected by the [50,200,-1,5] parameters (the range is 50 to 200, the
behavior exponential, and the aspect is a nice slider), and so on.

iwidth (optional) -- width of the rectangular area containing all
sliders of the bank, excluding text labels, that are placed below that
area.

iheight (optional) -- height of the rectangular area containing all
sliders of the bank, excluding text labels, that are placed below that
area.

ix (optional) -- horizontal position of the upper left corner of the
rectangular area containing all sliders belonging to the bank. You have
to leave enough space, below that rectangle, in order to make sure
labels of sliders to be visible. This is because the labels themselves
are external to the rectangular area.

iy (optional) -- vertical position of the upper left corner of the
rectangular area containing all sliders belonging to the bank. You have
to leave enough space, below that rectangle, in order to make sure
labels of sliders to be visible. This is because the labels themselves
are external to the rectangular area.

istart_index (optional, default=0) -- an integer number referring to a
starting offset of output cell locations. It can be positive to allow
multiple banks of sliders to output in the same table or in the zak
space. The default value is zero (no offset).

  Performance

There are no k-rate arguments, even if cells of the output table (or the
zak space) are updated at k-rate.

FLvslidBnk2 is a widget containing a bank of vertical sliders. Any
number of sliders can be placed into the bank (inumsliders argument).
The output of all sliders is stored into a previously allocated table or
into the zak space (ioutable argument). It is possible to determine the
first location of the table (or of the zak space) in which to store the
output of the first slider by means of istart_index argument.

Each slider can have an individual label that is placed below it. Labels
are defined by the “names” argument. The output range of each slider can
be individually set by means of the min and max values inside the
iconfigtable table. The curve response of each slider can be set
individually, by means of a list of identifiers placed in the
iconfigtable table (exp argument). It is possible to define the aspect
of each slider independently or to make all sliders have the same aspect
(style argument in the iconfigtable table).

The iwidth, iheight, ix, and iy arguments determine width, height,
horizontal and vertical position of the rectangular area containing
sliders. Notice that the label of each slider is placed below them and
is not included in the rectangular area containing sliders. So the user
should leave enough space below the bank by assigning a proper iy value
in order to leave labels visible.

FLvslidBnk2 is identical to FLslidBnk2 except it contains vertical
sliders instead of horizontal. Since the width of each single slider is
often small, it is recommended to leave only a single space in the names
string (“ “), in this case each slider will be automatically numbered.

  IMPORTANT!

Notice that the tables used by FLvslidBnk2 must be created with the
ftgen opcode and placed in the orchestra before the corresponding
valuator. They can not placed in the score. This is because tables
placed in the score are created later than the initialization of the
opcodes placed in the header section of the orchestra.


===========================================================================
FLxyin                                                               *FLxyin*

  Description

Similar to xyin, sense the mouse cursor position in a user-defined area
inside an FLpanel.

  Syntax

koutx, kouty, kinside  FLxyin ioutx_min, ioutx_max, iouty_min, iouty_max, \
      iwindx_min, iwindx_max, iwindy_min, iwindy_max [, iexpx, iexpy, ioutx, iouty]

  Initialization

ioutx_min, ioutx_max - the minimum and maximum limits of the interval to
be output (X or horizontal axis).

iouty_min, iouty_max - the minimum and maximum limits of the interval to
be output (Y or vertical axis).

iwindx_min, iwindx_max - the X coordinate of the horizontal edges of the
sensible area, relative to the FLpanel ,in pixels.

iwindy_min, iwindy_max - the Y coordinates of the vertical edges of the
sensible area, relative to the FLpanel, in pixels.

iexpx, iexpy - (optional) integer numbers denoting the behavior of the x
or y output: 0 -> output is linear; -1 -> output is exponential; any
other number indicates the number of an existing table that is used for
indexing. With a positive value for table number, linear interpolation
is provided in table indexing. A negative table number suppresses
interpolation. Notice that in normal operations, the table should be
normalized and unipolar (i.e. all table elements should be in the zero
to one range). In this case all table elements will be rescaled
according to imax and imin. Anyway, it is possible to use non-normalized
tables (created with a negative table number, that can contain elements
of any value), in order to access the actual values of table elements,
without rescaling, by assigning 0 to iout_min and 1 to iout_max.

ioutx, iouty – (optional) initial output values.

  Performance

koutx, kouty - output values, scaled according to user choices.

kinside - a flag that informs if the mouse cursor falls out of the
rectangle of the user-defined area. If it is out of the area, kinside is
set to zero.

FLxyin senses the mouse cursor position in a user-defined area inside an
FLpanel. When FLxyin is called, the position of the mouse within the
chosen area is returned at k-rate. It is possible to define the sensible
area, as well the minimum and maximum values corresponding to the
minimum and maximum mouse positions. Mouse buttons don’t need to be
pressed to make FLxyin to operate. It is able to function correctly even
if other widgets (present in the FLpanel) overlap the sensible area.

FLxyin unlike most other FLTK opcodes can't be used inside the header,
since it is not a widget. It is just a definition of an area for mouse
sensing within an FLTK panel.


===========================================================================
fmb3                                                                   *fmb3*

  Description

Uses FM synthesis to create a Hammond B3 organ sound. It comes from a
family of FM sounds, all using 4 basic oscillators and various
architectures, as used in the TX81Z synthesizer.

  Syntax

ares fmb3 kamp, kfreq, kc1, kc2, kvdepth, kvrate[, ifn1, ifn2, ifn3, \
      ifn4, ivfn]

  Initialization

fmb3 takes 5 tables for initialization. The first 4 are the basic inputs
and the last is the low frequency oscillator (LFO) used for vibrato. The
last table should usually be a sine wave. These all default to a sine
wave table.

The initial waves should be:

  * ifn1 -- sine wave

  * ifn2 -- sine wave

  * ifn3 -- sine wave

  * ifn4 -- sine wave

  Performance

kamp -- Amplitude of note.

kfreq -- Frequency of note played.

kc1, kc2 -- Controls for the synthesizer:

  * kc1 -- Total mod index

  * kc2 -- Crossfade of two modulators

  * Algorithm -- 4

kvdepth -- Vibrator depth

kvrate -- Vibrator rate


===========================================================================
fmbell                                                               *fmbell*

  Description

Uses FM synthesis to create a tublar bell sound. It comes from a family
of FM sounds, all using 4 basic oscillators and various architectures,
as used in the TX81Z synthesizer.

  Syntax

ares fmbell kamp, kfreq, kc1, kc2, kvdepth, kvrate[, ifn1, ifn2, ifn3, \
      ifn4, ivfn, isus]

  Initialization

All these opcodes take 5 tables for initialization. The first 4 are the
basic inputs and the last is the low frequency oscillator (LFO) used for
vibrato. These all default to a siewave table.

The initial waves should be:

  * ifn1 -- sine wave

  * ifn2 -- sine wave

  * ifn3 -- sine wave

  * ifn4 -- sine wave

The optional argument isus controls how long the sound lasts, or how
quickly it decays. It defaults to 4.

  Performance

kamp -- Amplitude of note.

kfreq -- Frequency of note played.

kc1, kc2 -- Controls for the synthesizer:

  * kc1 -- Mod index 1

  * kc2 -- Crossfade of two outputs

  * Algorithm -- 5

kvdepth -- Vibrator depth

kvrate -- Vibrator rate


===========================================================================
fmmetal                                                             *fmmetal*

  Description

Uses FM synthesis to create a “Heavy Metal” sound. It comes from a
family of FM sounds, all using 4 basic oscillators and various
architectures, as used in the TX81Z synthesizer.

  Syntax

ares fmmetal kamp, kfreq, kc1, kc2, kvdepth, kvrate, ifn1, ifn2, ifn3, \
      ifn4, ivfn

  Initialization

All these opcodes take 5 tables for initialization. The first 4 are the
basic inputs and the last is the low frequency oscillator (LFO) used for
vibrato. The last table should usually be a sine wave.

The initial waves should be:

  * ifn1 -- sine wave

  * ifn2 -- twopeaks.aiff

  * ifn3 -- twopeaks.aiff

  * ifn4 -- sine wave

  Note

The file “twopeaks.aiff” is also available at
ftp://ftp.cs.bath.ac.uk/pub/dream/documentation/sounds/modelling/.

  Performance

kamp -- Amplitude of note.

kfreq -- Frequency of note played.

kc1, kc2 -- Controls for the synthesizer:

  * kc1 -- Total mod index

  * kc2 -- Crossfade of two modulators

  * Algorithm -- 3

kvdepth -- Vibrator depth

kvrate -- Vibrator rate


===========================================================================
fmpercfl                                                           *fmpercfl*

  Description

Uses FM synthesis to create a percussive flute sound. It comes from a
family of FM sounds, all using 4 basic oscillators and various
architectures, as used in the TX81Z synthesizer.

  Syntax

ares fmpercfl kamp, kfreq, kc1, kc2, kvdepth, kvrate[, ifn1, ifn2, \
      ifn3, ifn4, ivfn]

  Initialization

All these opcodes take 5 tables for initialization. The first 4 are the
basic inputs and the last is the low frequency oscillator (LFO) used for
vibrato. These all default to a sine wave table.

The initial waves should be:

  * ifn1 -- sine wave

  * ifn2 -- sine wave

  * ifn3 -- sine wave

  * ifn4 -- sine wave

  Performance

kamp -- Amplitude of note.

kfreq -- Frequency of note played.

kc1, kc2 -- Controls for the synthesizer:

  * kc1 -- Total mod index

  * kc2 -- Crossfade of two modulators

  * Algorithm -- 4

kvdepth -- Vibrator depth

kvrate -- Vibrator rate


===========================================================================
fmrhode                                                             *fmrhode*

  Description

Uses FM synthesis to create a Fender Rhodes electric piano sound. It
comes from a family of FM sounds, all using 4 basic oscillators and
various architectures, as used in the TX81Z synthesizer.

  Syntax

ares fmrhode kamp, kfreq, kc1, kc2, kvdepth, kvrate, ifn1, ifn2, \
      ifn3, ifn4, ivfn

  Initialization

All these opcodes take 5 tables for initialization. The first 4 are the
basic inputs and the last is the low frequency oscillator (LFO) used for
vibrato. The last table should usually be a sine wave.

The initial waves should be:

  * ifn1 -- sine wave

  * ifn2 -- sine wave

  * ifn3 -- sine wave

  * ifn4 -- fwavblnk.aiff

  Note

The file “fwavblnk.aiff” is also available at
ftp://ftp.cs.bath.ac.uk/pub/dream/documentation/sounds/modelling/.

  Performance

kamp -- Amplitude of note.

kfreq -- Frequency of note played.

kc1, kc2 -- Controls for the synthesizer:

  * kc1 -- Mod index 1

  * kc2 -- Crossfade of two outputs

  * Algorithm -- 5

kvdepth -- Vibrator depth

kvrate -- Vibrator rate


===========================================================================
fmvoice                                                             *fmvoice*

  Description

FM Singing Voice Synthesis

  Syntax

ares fmvoice kamp, kfreq, kvowel, ktilt, kvibamt, kvibrate[, ifn1, \
      ifn2, ifn3, ifn4, ivibfn]

  Initialization

ifn1, ifn2, ifn3,ifn3, ivibfn -- Tables, usually of sinewaves. The last
is for vibrato

  Performance

kamp -- Amplitude of note.

kfreq -- Frequency of note played.

kvowel -- the vowel being sung, in the range 0-64

ktilt -- the spectral tilt of the sound in the range 0 to 99

kvibamt -- Depth of vibrato

kvibrate -- Rate of vibrato


===========================================================================
fmwurlie                                                           *fmwurlie*

  Description

Uses FM synthesis to create a Wurlitzer electric piano sound. It comes
from a family of FM sounds, all using 4 basic oscillators and various
architectures, as used in the TX81Z synthesizer.

  Syntax

ares fmwurlie kamp, kfreq, kc1, kc2, kvdepth, kvrate, ifn1, ifn2, ifn3, \
      ifn4, ivfn

  Initialization

All these opcodes take 5 tables for initialization. The first 4 are the
basic inputs and the last is the low frequency oscillator (LFO) used for
vibrato. The last table should usually be a sine wave.

The initial waves should be:

  * ifn1 -- sine wave

  * ifn2 -- sine wave

  * ifn3 -- sine wave

  * ifn4 -- fwavblnk.aiff

  Note

The file “fwavblnk.aiff” is also available at
ftp://ftp.cs.bath.ac.uk/pub/dream/documentation/sounds/modelling/.

  Performance

kamp -- Amplitude of note.

kfreq -- Frequency of note played.

kc1, kc2 -- Controls for the synthesizer:

  * kc1 -- Mod index 1

  * kc2 -- Crossfade of two outputs

  * Algorithm -- 5

kvdepth -- Vibrator depth

kvrate -- Vibrator rate


===========================================================================
fof                                                                     *fof*

  Description

Audio output is a succession of sinusoid bursts initiated at frequency
xfund with a spectral peak at xform. For xfund above 25 Hz these bursts
produce a speech-like formant with spectral characteristics determined
by the k-input parameters. For lower fundamentals this generator
provides a special form of granular synthesis.

  Syntax

ares fof xamp, xfund, xform, koct, kband, kris, kdur, kdec, iolaps, \
      ifna, ifnb, itotdur [, iphs] [, ifmode] [, iskip]

  Initialization

iolaps -- number of preallocated spaces needed to hold overlapping burst
data. Overlaps are frequency dependent, and the space required depends
on the maximum value of xfund * kdur. Can be over-estimated at no
computation cost. Uses less than 50 bytes of memory per iolap.

ifna, ifnb -- table numbers of two stored functions. The first is a sine
table for sineburst synthesis (size of at least 4096 recommended). The
second is a rise shape, used forwards and backwards to shape the
sineburst rise and decay; this may be linear (GEN07) or perhaps a
sigmoid (GEN19).

itotdur -- total time during which this fof will be active. Normally set
to p3. No new sineburst is created if it cannot complete its kdur within
the remaining itotdur.

iphs (optional, default=0) -- initial phase of the fundamental,
expressed as a fraction of a cycle (0 to 1). The default value is 0.

ifmode (optional, default=0) -- formant frequency mode. If zero, each
sineburst keeps the xform frequency it was launched with. If non-zero,
each is influenced by xform continuously. The default value is 0.

iskip (optional, default=0) -- If non-zero, skip initialisation (allows
legato use).

  Performance

xamp -- peak amplitude of each sineburst, observed at the true end of
its rise pattern. The rise may exceed this value given a large bandwidth
(say, Q < 10) and/or when the bursts are overlapping.

xfund -- the fundamental frequency (in Hertz) of the impulses that
create new sinebursts.

xform -- the formant frequency, i.e. freq of the sinusoid burst induced
by each xfund impulse. This frequency can be fixed for each burst or can
vary continuously (see ifmode).

koct -- octaviation index, normally zero. If greater than zero, lowers
the effective xfund frequency by attenuating odd-numbered sinebursts.
Whole numbers are full octaves, fractions transitional.

kband -- the formant bandwidth (at -6dB), expressed in Hz. The bandwidth
determines the rate of exponential decay throughout the sineburst,
before the enveloping described below is applied.

kris, kdur, kdec -- rise, overall duration, and decay times (in seconds)
of the sinusoid burst. These values apply an enveloped duration to each
burst, in similar fashion to a Csound linen generator but with rise and
decay shapes derived from the ifnb input. kris inversely determines the
skirtwidth (at -40 dB) of the induced formant region. kdur affects the
density of sineburst overlaps, and thus the speed of computation.
Typical values for vocal imitation are .003,.02,.007.

Csound's fof generator is loosely based on Michael Clarke's C-coding of
IRCAM's CHANT program (Xavier Rodet et al.). Each fof produces a single
formant, and the output of four or more of these can be summed to
produce a rich vocal imitation. fof synthesis is a special form of
granular synthesis, and this implementation aids transformation between
vocal imitation and granular textures. Computation speed depends on
kdur, xfund, and the density of any overlaps.


===========================================================================
fof2                                                                   *fof2*

  Description

Audio output is a succession of sinusoid bursts initiated at frequency
xfund with a spectral peak at xform. For xfund above 25 Hz these bursts
produce a speech-like formant with spectral characteristics determined
by the k-input parameters. For lower fundamentals this generator
provides a special form of granular synthesis.

fof2 implements k-rate incremental indexing into ifna function with each
successive burst.

  Syntax

ares fof2 xamp, xfund, xform, koct, kband, kris, kdur, kdec, iolaps, \
      ifna, ifnb, itotdur, kphs, kgliss [, iskip]

  Initialization

iolaps -- number of preallocated spaces needed to hold overlapping burst
data. Overlaps are frequency dependent, and the space required depends
on the maximum value of xfund * kdur. Can be over-estimated at no
computation cost. Uses less than 50 bytes of memory per iolap.

ifna, ifnb -- table numbers of two stored functions. The first is a sine
table for sineburst synthesis (size of at least 4096 recommended). The
second is a rise shape, used forwards and backwards to shape the
sineburst rise and decay; this may be linear (GEN07) or perhaps a
sigmoid (GEN19).

itotdur -- total time during which this fof will be active. Normally set
to p3. No new sineburst is created if it cannot complete its kdur within
the remaining itotdur.

iskip (optional, default=0) -- If non-zero, skip initialization (allows
legato use).

  Performance

xamp -- peak amplitude of each sineburst, observed at the true end of
its rise pattern. The rise may exceed this value given a large bandwidth
(say, Q < 10) and/or when the bursts are overlapping.

xfund -- the fundamental frequency (in Hertz) of the impulses that
create new sinebursts.

xform -- the formant frequency, i.e. freq of the sinusoid burst induced
by each xfund impulse. This frequency can be fixed for each burst or can
vary continuously (see ifmode).

koct -- octaviation index, normally zero. If greater than zero, lowers
the effective xfund frequency by attenuating odd-numbered sinebursts.
Whole numbers are full octaves, fractions transitional.

kband -- the formant bandwidth (at -6dB), expressed in Hz. The bandwidth
determines the rate of exponential decay throughout the sineburst,
before the enveloping described below is applied.

kris, kdur, kdec -- rise, overall duration, and decay times (in seconds)
of the sinusoid burst. These values apply an enveloped duration to each
burst, in similar fashion to a Csound linen generator but with rise and
decay shapes derived from the ifnb input. kris inversely determines the
skirtwidth (at -40 dB) of the induced formant region. kdur affects the
density of sineburst overlaps, and thus the speed of computation.
Typical values for vocal imitation are .003,.02,.007.

kphs -- allows k-rate indexing of function table ifna with each
successive burst, making it suitable for time-warping applications.
Values of kphs are normalized from 0 to 1, 1 being the end of the
function table ifna.

kgliss -- sets the end pitch of each grain relative to the initial
pitch, in octaves. Thus kgliss = 2 means that the grain ends two octaves
above its initial pitch, while kgliss = -3/4 has the grain ending a
major sixth below. Each 1/12 added to kgliss raises the ending frequency
one half-step. If you want no glissando, set kgliss to 0.

Csound's fof generator is loosely based on Michael Clarke's C-coding of
IRCAM's CHANT program (Xavier Rodet et al.). Each fof produces a single
formant, and the output of four or more of these can be summed to
produce a rich vocal imitation. fof synthesis is a special form of
granular synthesis, and this implementation aids transformation between
vocal imitation and granular textures. Computation speed depends on
kdur, xfund, and the density of any overlaps.

  Note

The ending frequency of any grain is equal to kform * (2 ^ kgliss), so
setting kgliss too high may result in aliasing. For example, kform =
3000 and kgliss = 3 places the ending frequency over the Nyquist if sr =
44100. It is a good idea to scale kgliss accordingly.


===========================================================================
fofilter                                                           *fofilter*

  Description

Fofilter generates a stream of overlapping sinewave grains, when fed
with a pulse train. Each grain is the impulse response of a combination
of two BP filters. The grains are defined by their attack time
(determining the skirtwidth of the formant region at -60dB) and decay
time (-6dB bandwidth). Overlapping will occur when 1/freq < decay, but,
unlike FOF, there is no upper limit on the number of overlaps. The
original idea for this opcode came from J McCartney's formlet class in
SuperCollider, but this is possibly implemented differently(?).

  Syntax

asig fofilter ain, xcf, xris, xdec[, istor]

  Initialization

istor --initial disposition of internal data space. Since filtering
incorporates a feedback loop of previous output, the initial status of
the storage space used is significant. A zero value will clear the
space; a non-zero value will allow previous information to remain. The
default value is 0.

  Performance

asig -- input signal.

xcf -- filter centre frequency

xris -- impulse response attack time (secs).

xdec -- impulse response decay time (secs).


===========================================================================
fog                                                                     *fog*

  Description

Audio output is a succession of grains derived from data in a stored
function table ifna. The local envelope of these grains and their timing
is based on the model of fof synthesis and permits detailed control of
the granular synthesis.

  Syntax

ares fog xamp, xdens, xtrans, aspd, koct, kband, kris, kdur, kdec, \
      iolaps, ifna, ifnb, itotdur [, iphs] [, itmode] [, iskip]

  Initialization

iolaps -- number of pre-located spaces needed to hold overlapping grain
data. Overlaps are density dependent, and the space required depends on
the maximum value of xdens * kdur. Can be over-estimated at no
computation cost. Uses less than 50 bytes of memory per iolap.

ifna, ifnb -- table numbers of two stored functions. The first is the
data used for granulation, usually from a soundfile (GEN01). The second
is a rise shape, used forwards and backwards to shape the grain rise and
decay; this is normally a sigmoid (GEN19) but may be linear (GEN05).

itotdur -- total time during which this fog will be active. Normally set
to p3. No new grain is created if it cannot complete its kdur within the
remaining itotdur.

iphs (optional) -- initial phase of the fundamental, expressed as a
fraction of a cycle (0 to 1). The default value is 0.

itmode (optional) -- transposition mode. If zero, each grain keeps the
xtrans value it was launched with. If non-zero, each is influenced by
xtrans continuously. The default value is 0.

iskip (optional, default=0) -- If non-zero, skip initialization (allows
legato use).

  Performance

xamp -- amplitude factor. Amplitude is also dependent on the number of
overlapping grains, the interaction of the rise shape (ifnb) and the
exponential decay (kband), and the scaling of the grain waveform (ifna).
The actual amplitude may therefore exceed xamp.

xdens -- density. The frequency of grains per second.

xtrans -- transposition factor. The rate at which data from the stored
function table ifna is read within each grain. This has the effect of
transposing the original material. A value of 1 produces the original
pitch. Higher values transpose upwards, lower values downwards. Negative
values result in the function table being read backwards.

aspd -- Starting index pointer. aspd is the normalized index (0 to 1) to
table ifna that determines the movement of a pointer used as the
starting point for reading data within each grain. (xtrans determines
the rate at which data is read starting from this pointer.)

koct -- octaviation index. The operation of this parameter is identical
to that in fof.

kband, kris, kdur, kdec -- grain envelope shape. These parameters
determine the exponential decay (kband), and the rise (kris), overall
duration (kdur,) and decay (kdec ) times of the grain envelope. Their
operation is identical to that of the local envelope parameters in fof.


===========================================================================
fold                                                                   *fold*

  Description

Adds artificial foldover to an audio signal.

  Syntax

ares fold asig, kincr

  Performance

asig -- input signal

kincr -- amount of foldover expressed in multiple of sampling rate. Must
be >= 1

fold is an opcode which creates artificial foldover. For example, when
kincr is equal to 1 with sr=44100, no foldover is added. When kincr is
set to 2, the foldover is equivalent to a downsampling to 22050, when it
is set to 4, to 11025 etc. Fractional values of kincr are possible,
allowing a continuous variation of foldover amount. This can be used for
a wide range of special effects.


===========================================================================
follow                                                               *follow*

  Description

Envelope follower unit generator.

  Syntax

ares follow asig, idt

  Initialization

idt -- This is the period, in seconds, that the average amplitude of
asig is reported. If the frequency of asig is low then idt must be large
(more than half the period of asig )

  Performance

asig -- This is the signal from which to extract the envelope.


===========================================================================
follow2                                                             *follow2*

  Description

A controllable envelope extractor using the algorithm attributed to
Jean-Marc Jot.

  Syntax

ares follow2 asig, katt, krel

  Performance

asig -- the input signal whose envelope is followed

katt -- the attack rate (60dB attack time in seconds)

krel -- the decay rate (60dB decay time in seconds)

The output tracks the amplitude envelope of the input signal. The rate
at which the output grows to follow the signal is controlled by the
katt, and the rate at which it decreases in response to a lower
amplitude, is controlled by the krel. This gives a smoother envelope
than follow.


===========================================================================
foscil                                                               *foscil*

  Description

A basic frequency modulated oscillator.

  Syntax

ares foscil xamp, kcps, xcar, xmod, kndx, ifn [, iphs]

  Initialization

ifn -- function table number. Requires a wrap-around guard point.

iphs (optional, default=0) -- initial phase of waveform in table ifn,
expressed as a fraction of a cycle (0 to 1). A negative value will cause
phase initialization to be skipped. The default value is 0.

  Performance

xamp -- the amplitude of the output signal.

kcps -- a common denominator, in cycles per second, for the carrier and
modulating frequencies.

xcar -- a factor that, when multiplied by the kcps parameter, gives the
carrier frequency.

xmod -- a factor that, when multiplied by the kcps parameter, gives the
modulating frequency.

kndx -- the modulation index.

foscil is a composite unit that effectively banks two oscil opcodes in
the familiar Chowning FM setup, wherein the audio-rate output of one
generator is used to modulate the frequency input of another (the
“carrier”). Effective carrier frequency = kcps * xcar, and modulating
frequency = kcps * xmod. For integral values of xcar and xmod, the
perceived fundamental will be the minimum positive value of kcps * (xcar
- n * xmod), n = 0,1,2,... The input kndx is the index of modulation
(usually time-varying and ranging 0 to 4 or so) which determines the
spread of acoustic energy over the partial positions given by n =
0,1,2,.., etc. ifn should point to a stored sine wave. Previous to
version 3.50, xcar and xmod could be k-rate only.

The actual formula used for this implementation of FM synthesis is xamp
* cos(2π * t * kcps * xcar + kndx * sin(2π * t * kcps * xmod) - π),
assuming that the table is a sine wave.


===========================================================================
foscili                                                             *foscili*

  Description

Basic frequency modulated oscillator with linear interpolation.

  Syntax

ares foscili xamp, kcps, xcar, xmod, kndx, ifn [, iphs]

  Initialization

ifn -- function table number. Requires a wrap-around guard point.

iphs (optional, default=0) -- initial phase of waveform in table ifn,
expressed as a fraction of a cycle (0 to 1). A negative value will cause
phase initialization to be skipped. The default value is 0.

  Performance

xamp -- the amplitude of the output signal.

kcps -- a common denominator, in cycles per second, for the carrier and
modulating frequencies.

xcar -- a factor that, when multiplied by the kcps parameter, gives the
carrier frequency.

xmod -- a factor that, when multiplied by the kcps parameter, gives the
modulating frequency.

kndx -- the modulation index.

foscili differs from foscil in that the standard procedure of using a
truncated phase as a sampling index is here replaced by a process that
interpolates between two successive lookups. Interpolating generators
will produce a noticeably cleaner output signal, but they may take as
much as twice as long to run. Adequate accuracy can also be gained
without the time cost of interpolation by using large stored function
tables of 2K, 4K or 8K points if the space is available.


===========================================================================
fout                                                                   *fout*

  Description

fout outputs N a-rate signals to a specified file of N channels.

  Syntax

fout ifilename, iformat, aout1 [, aout2, aout3,...,aoutN]

fout ifilename, iformat, array[]

  Initialization

ifilename -- the output file's name (in double-quotes).

iformat -- a flag to choose output file format (note: Csound versions
older than 5.0 may only support formats 0, 1, and 2):

  * 0 - 32-bit floating point samples without header (binary PCM
    multichannel file)

  * 1 - 16-bit integers without header (binary PCM multichannel file)

  * 2 - 16-bit integers with a header. The header type depends on the
    render (-o) format. For example, if the user chooses the AIFF format
    (using the -A flag), the header format will be AIFF type.

  * 3 - u-law samples with a header (see iformat=2).

  * 4 - 16-bit integers with a header (see iformat=2).

  * 5 - 32-bit integers with a header (see iformat=2).

  * 6 - 32-bit floats with a header (see iformat=2).

  * 7 - 8-bit unsigned integers with a header (see iformat=2).

  * 8 - 24-bit integers with a header (see iformat=2).

  * 9 - 64-bit floats with a header (see iformat=2).

In addition, Csound versions 5.0 and later allow for explicitly
selecting a particular header type by specifying the format as 10 *
fileType + sampleFormat, where fileType may be 1 for WAV, 2 for AIFF, 3
for raw (headerless) files, and 4 for IRCAM; sampleFormat is one of the
above values in the range 0 to 9, except sample format 0 is taken from
the command line (-o), format 1 is 8-bit signed integers, and format 2
is a-law. So, for example, iformat=25 means 32-bit integers with AIFF
header.

  Performance

aout1,... aoutN -- signals to be written to the file. In the case of raw
files, the expected range of audio signals is determined by the selected
sample format; for sound files with a header like WAV and AIFF, the
audio signals should be in the range -0dbfs to 0dbfs.

fout (file output) writes samples of audio signals to a file with any
number of channels. Channel number depends by the number of aoutN
variables (i.e. a mono signal with only an a-rate argument, a stereo
signal with two a-rate arguments etc.) Maximum number of channels is
fixed to 64. Multiple fout opcodes can be present in the same
instrument, referring to different files.

Notice that, unlike out, outs and outq, fout does not zero the audio
variable so you must zero it after calling it. If polyphony is to be
used, you can use vincr and clear opcodes for this task.

Notice that fout and foutk can use either a string containing a file
pathname, or a handle-number generated by fiopen. Whereas, with fouti
and foutir, the target file can be only specified by means of a
handle-number.

  Note

If you are using fout to generate an audio file for the global output of
csound, you might want to use the monitor opcode, which can tap the
output buffer, to avoid having to route


===========================================================================
fouti                                                                 *fouti*

  Description

fouti output N i-rate signals to a specified file of N channels.

  Syntax

fouti ihandle, iformat, iflag, iout1 [, iout2, iout3,....,ioutN]

  Initialization

ihandle -- a number which specifies this file.

iformat -- a flag to choose output file format:

  * 0 - floating point in text format

  * 1 - 32-bit floating point in binary format

iflag -- choose the mode of writing to the ASCII file (valid only in
ASCII mode; in binary mode iflag has no meaning, but it must be present
anyway). iflag can be a value chosen among the following:

  * 0 - line of text without instrument prefix

  * 1 - line of text with instrument prefix (see below)

  * 2 - reset the time of instrument prefixes to zero (to be used only
    in some particular cases. See below)

iout,..., ioutN -- values to be written to the file

  Performance

fouti and foutir write i-rate values to a file. The main use of these
opcodes is to generate a score file during a realtime session. For this
purpose, the user should set iformat to 0 (text file output) and iflag
to 1, which enable the output of a prefix consisting of the strings
inum, actiontime, and duration, before the values of iout1...ioutN
arguments. The arguments in the prefix refer to instrument number,
action time and duration of current note.

Notice that fout and foutk can use either a string containing a file
pathname, or a handle-number generated by fiopen. Whereas, with fouti
and foutir, the target file can be only specified by means of a
handle-number.


===========================================================================
foutir                                                               *foutir*

  Description

foutir output N i-rate signals to a specified file of N channels.

  Syntax

foutir ihandle, iformat, iflag, iout1 [, iout2, iout3,....,ioutN]

  Initialization

ihandle -- a number which specifies this file.

iformat -- a flag to choose output file format:

  * 0 - floating point in text format

  * 1 - 32-bit floating point in binary format

iflag -- choose the mode of writing to the ASCII file (valid only in
ASCII mode; in binary mode iflag has no meaning, but it must be present
anyway). iflag can be a value chosen among the following:

  * 0 - line of text without instrument prefix

  * 1 - line of text with instrument prefix (see below)

  * 2 - reset the time of instrument prefixes to zero (to be used only
    in some particular cases. See below)

iout,..., ioutN -- values to be written to the file

  Performance

fouti and foutir write i-rate values to a file. The main use of these
opcodes is to generate a score file during a realtime session. For this
purpose, the user should set iformat to 0 (text file output) and iflag
to 1, which enable the output of a prefix consisting of the strings
inum, actiontime, and duration, before the values of iout1...ioutN
arguments. The arguments in the prefix refer to instrument number,
action time and duration of current note.

The difference between fouti and foutir is that, in the case of fouti,
when iflag is set to 1, the duration of the first opcode is undefined
(so it is replaced by a dot). Whereas, foutir is defined at the end of
note, so the corresponding text line is written only at the end of the
current note (in order to recognize its duration). The corresponding
file is linked by the ihandle value generated by the fiopen opcode. So
fouti and foutir can be used to generate a Csound score while playing a
realtime session.

Notice that fout and foutk can use either a string containing a file
pathname, or a handle-number generated by fiopen. Whereas, with fouti
and foutir, the target file can be only specified by means of a
handle-number.


===========================================================================
foutk                                                                 *foutk*

  Description

foutk outputs N k-rate signals to a specified file of N channels.

  Syntax

foutk ifilename, iformat, kout1 [, kout2, kout3,....,koutN]

  Initialization

ifilename -- the output file's name (in double-quotes).

iformat -- a flag to choose output file format (note: Csound versions
older than 5.0 may only support formats 0 and 1):

  * 0 - 32-bit floating point samples without header (binary PCM
    multichannel file)

  * 1 - 16-bit integers without header (binary PCM multichannel file)

  * 2 - 16-bit integers without header (binary PCM multichannel file)

  * 3 - u-law samples without header

  * 4 - 16-bit integers without header

  * 5 - 32-bit integers without header

  * 6 - 32-bit floats without header

  * 7 - 8-bit unsigned integers without header

  * 8 - 24-bit integers without header

  * 9 - 64-bit floats without header

  Performance

kout1,...koutN -- control-rate signals to be written to the file. The
expected range of the signals is determined by the selected sample format.

foutk operates in the same way as fout, but with k-rate signals. iformat
can be set only in the range 0 to 9, or 0 to 1 with an old version of
Csound.

Notice that fout and foutk can use either a string containing a file
pathname, or a handle-number generated by fiopen. Whereas, with fouti
and foutir, the target file can be only specified by means of a
handle-number.


===========================================================================
fprintks                                                           *fprintks*

  Description

Similar to printks but prints to a file.

  Syntax

fprintks "filename", "string", [, kval1] [, kval2] [...]

  Initialization

"filename" -- name of the output file.

"string" -- the text string to be printed. Can be up to 8192 characters
and must be in double quotes.

  Performance

kval1, kval2, ... (optional) -- The k-rate values to be printed. These
are specified in “string” with the standard C value specifier (%f, %d,
etc.) in the order given.

fprintks is similar to the printks opcode except it outputs to a file
and doesn't have a itime parameter. For more information about output
formatting, please look at printks's documentation.


===========================================================================
fprints                                                             *fprints*

  Description

Similar to prints but prints to a file.

  Syntax

fprints "filename", "string" [, ival1] [, ival2] [...]

  Initialization

"filename" -- name of the output file.

"string" -- the text string to be printed. Can be up to 8192 characters
and must be in double quotes.

ival1, ival2, ... (optional) -- The i-rate values to be printed. These
are specified in “string” with the standard C value specifier (%f, %d,
etc.) in the order given.

  Performance

fprints is similar to the prints opcode except it outputs to a file. For
more information about output formatting, please look at printks's
documentation.


===========================================================================
frac                                                                   *frac*

  Description

Returns the fractional part of x.

  Syntax

frac(x) (init-rate or control-rate args; also works at audio rate in Csound5)

where the argument within the parentheses may be an expression. Value
converters perform arithmetic translation from units of one kind to
units of another. The result can then be a term in a further expression.


===========================================================================
fractalnoise                                                   *fractalnoise*

  Description

A fractal noise generator implemented as a white noise filtered by a
cascade of 15 first-order filters.

  Syntax

ares fractalnoise kamp, kbeta

  Performance

kamp -- amplitude.

kbeta -- spectral parameter related to the fractal dimension

  * 0 - white

  * 1 - pink

  * 2 - brown


===========================================================================
framebuffer                                                     *framebuffer*

  Description

framebuffer converts audio signals into a 1 dimensional k-rate array of
a specified size. The size of the k-rate array must be larger than
ksmps. It also converts 1 dimensional k-rate arrays back into audio
signals, the k-rate arrays must be uninitialised and also be larger than
ksmps in size. The buffer works as a circular buffer and may be used for
doing frame based audio processing such as spectral analysis/synthesis
or as a simple delay line.

  Syntax

kout[] framebuffer ain, isize

aout framebuffer kin, isize

  Initialization

isize -- The amount of samples that the buffer will contain.

  Performance

kout[] -- The k-rate array output from the framebuffer. ain -- The audio
signal input to the framebuffer.

aout -- The audio signal output from the framebuffer. kin -- The k-rate
array input to the framebuffer.


===========================================================================
freeverb                                                           *freeverb*

  Description

freeverb is a stereo reverb unit based on Jezar's public domain C++
sources, composed of eight parallel comb filters on both channels,
followed by four allpass units in series. The filters on the right
channel are slightly detuned compared to the left channel in order to
create a stereo effect.

  Syntax

aoutL, aoutR freeverb ainL, ainR, kRoomSize, kHFDamp[, iSRate[, iSkip]] 

  Initialization

iSRate (optional, defaults to 44100): adjusts the reverb parameters for
use with the specified sample rate (this will affect the length of the
delay lines in samples, and, as of the latest CVS version, the high
frequency attenuation). Only integer multiples of 44100 will reproduce
the original character of the reverb exactly, so it may be useful to set
this to 44100 or 88200 for an orchestra sample rate of 48000 or 96000
Hz, respectively. While iSRate is normally expected to be close to the
orchestra sample rate, different settings may be useful for special
effects.

iSkip (optional, defaults to zero): if non-zero, initialization of the
opcode will be skipped, whenever possible.

  Performance

ainL, ainR -- input signals; usually both are the same, but different
inputs can be used for special effect

  Note

It is recommended to process the input signal(s) with the denorm opcode
in order to avoid denormalized numbers which could significantly
increase CPU usage in some cases

aoutL, aoutR -- output signals for left and right channel

kRoomSize (range: 0 to 1) -- controls the length of the reverb, a higher
value means longer reverb. Settings above 1 may make the opcode unstable.

kHFDamp (range: 0 to 1): high frequency attenuation; a value of zero
means all frequencies decay at the same rate, while higher settings will
result in a faster decay of the high frequency range.


===========================================================================
ftchnls                                                             *ftchnls*

  Description

Returns the number of channels in a stored function table.

  Syntax

ftchnls(x) (init-rate args only)

  Performance

Returns the number of channels of a GEN01 table, determined from the
header of the original file. If the original file has no header or the
table was not created by these GEN01, ftchnls returns -1.


===========================================================================
ftconv                                                               *ftconv*

  Description

Low latency multichannel convolution, using a function table as impulse
response source. The algorithm is to split the impulse response to
partitions of length determined by the iplen parameter, and delay and
mix partitions so that the original, full length impulse response is
reconstructed without gaps. The output delay (latency) is iplen samples,
and does not depend on the control rate, unlike in the case of other
convolve opcodes.

  Syntax

a1[, a2[, a3[, ... a8]]] ftconv ain, ift, iplen[, iskipsamples \
      [, iirlen[, iskipinit]]]

  Initialization

ift -- source ftable number. The table is expected to contain
interleaved multichannel audio data, with the number of channels equal
to the number of output variables (a1, a2, etc.). An interleaved table
can be created from a set of mono tables with GEN52.

iplen -- length of impulse response partitions, in sample frames; must
be an integer power of two. Lower settings allow for shorter output
delay, but will increase CPU usage.

iskipsamples (optional, defaults to zero) -- number of sample frames to
skip at the beginning of the table. Useful for reverb responses that
have some amount of initial delay. If this delay is not less than iplen
samples, then setting iskipsamples to the same value as iplen will
eliminate any additional latency by ftconv.

iirlen (optional) -- total length of impulse response, in sample frames.
The default is to use all table data (not including the guard point).

iskipinit (optional, defaults to zero) -- if set to any non-zero value,
skip initialization whenever possible without causing an error.

  Performance

ain -- input signal.

a1 ... a8 -- output signal(s).


===========================================================================
ftcps                                                                 *ftcps*

  Description

Returns the base frequency of a stored function table in Hz..

  Syntax

ftcps(x) (init-rate args only)

  Performance

Returns the base frequency of stored function table, number x. ftcps is
designed for tables storing audio waveforms read from files (see GEN01).

ftcps returns -1 in case of an error (no base frequency set in table or
non-existent table).


===========================================================================
ftfree                                                               *ftfree*

  Description

Deletes function table.

  Syntax

ftfree ifno, iwhen

  Initialization

ifno -- the number of the table to be deleted

iwhen -- if zero the table is deleted at init time; otherwise the table
number is registered for being deleted at note deactivation.


===========================================================================
ftgen                                                                 *ftgen*

  Description

Generate a score function table from within the orchestra.

  Syntax

gir ftgen ifn, itime, isize, igen, iarga [, iargb ] [...]

  Initialization

gir -- either a requested or automatically assigned table number above 100.

ifn -- requested table number If ifn is zero, the number is assigned
automatically and the value placed in gir. Any other value is used as
the table number

itime -- is ignored, but otherwise corresponds to p2 in the score f
statement.

isize -- table size. Corresponds to p3 of the score f statement.

igen -- function table GEN routine. Corresponds to p4 of the score f
statement.

iarga, iargb, ... -- function table arguments. Correspond to p5 through
pn of the score f statement.

  Performance

This is equivalent to table generation in the score with the f statement.

  Note

Csound was originally designed to support tables with power of two sizes
only. Though this has changed in recent versions (you can use any size
by using a negative number), many opcodes will not accept them.

  Warning

Although Csound will not protest if ftgen is used inside instr-endin
statements, this is not the intended or supported use, and must be
handled with care as it has global effects. (In particular, a different
size usually leads to relocation of the table, which may cause a crash
or otherwise erratic behaviour.


===========================================================================
ftgenonce                                                         *ftgenonce*

  Description

Enables the creation of function tables entirely inside instrument
definitions, without any duplication of data.

The ftgenonce opcode is designed to simplify writing instrument
definitions that can be re-used in different orchestras simply by
#including them and plugging them into some output instrument. There is
no need to define function tables either in the score, or in the
orchestra header.

The ftgenonce opcode is similar to ftgentmp, and has identical
arguments. However, function tables are neither duplicated nor deleted.
Instead, all of the arguments to the opcode are concatenated to form the
key to a lookup table that points to the function table number. Thus,
every request to ftgenonce with the same arguments receives the same
instance of the function table data. Every change in the value of any
ftgenonce argument causes the creation of a new function table.

  Syntax

ifno ftgenonce ip1, ip2dummy, isize, igen, iarga, iargb, ...

  Initialization

ifno -- an automatically assigned table number.

ip1 -- the number of the table to be generated or 0 if the number is to
be assigned.

ip2dummy -- ignored.

isize -- table size. Corresponds to p3 of the score f statement.

igen -- function table GEN routine. Corresponds to p4 of the score f
statement.

iarga, iargb, ... -- function table arguments. Correspond to p5 through
pn of the score f statement.

  Note

Csound was originally designed to support tables with power of two sizes
only. Though this has changed in recent versions (you can use any size
by using a negative number), many opcodes will not accept them.


===========================================================================
ftgentmp                                                           *ftgentmp*

  Description

Generate a score function table from within the orchestra, which is
optionally deleted at the end of the note.

  Syntax

ifno ftgentmp ip1, ip2dummy, isize, igen, iarga, iargb, ...

  Initialization

ifno -- either a requested or automatically assigned table number above
100.

ip1 -- the number of the table to be generated or 0 if the number is to
be assigned, in which case the table is deleted at the end of the note
activation.

ip2dummy -- ignored.

isize -- table size. Corresponds to p3 of the score f statement.

igen -- function table GEN routine. Corresponds to p4 of the score f
statement.

iarga, iargb, ... -- function table arguments. Correspond to p5 through
pn of the score f statement.

  Note

Csound was originally designed to support tables with power of two sizes
only. Though this has changed in recent versions (you can use any size
by using a negative number), many opcodes will not accept them.


===========================================================================
ftlen                                                                 *ftlen*

  Description

Returns the size of a stored function table.

  Syntax

ftlen(x) (init-rate args only)

  Performance

Returns the size (number of points, excluding guard point) of stored
function table, number x. While most units referencing a stored table
will automatically take its size into account (so tables can be of
arbitrary length), this function reports the actual size if that is
needed. Note that ftlen will always return a power-of-2 value, i.e. the
function table guard point (see f Statement) is not included.As of
Csound version 3.53, ftlen works with deferred function tables (see GEN01).

ftlen differs from nsamp in that nsamp gives the number of sample frames
loaded, while ftlen gives the total number of samples without the guard
point. For example, with a stereo sound file of 10000 samples, ftlen()
would return 19999 (i.e. a total of 20000 mono samples, not including a
guard point), but nsamp() returns 10000.


===========================================================================
ftload                                                               *ftload*

  Description

Load a set of previously-allocated tables from a file.

  Syntax

ftload "filename", iflag, ifn1 [, ifn2] [...]

  Initialization

"filename" -- A quoted string containing the name of the file to load.

iflag -- Type of the file to load/save. (0 = binary file, Non-zero =
text file)

ifn1, ifn2, ... -- Numbers of tables to load.

  Performance

ftload loads a list of tables from a file. (The tables have to be
already allocated though.) The file's format can be binary or text.

  Warning

The file's format is not compatible with a WAV-file and is not endian-safe.


===========================================================================
ftloadk                                                             *ftloadk*

  Description

Load a set of previously-allocated tables from a file.

  Syntax

ftloadk "filename", ktrig, iflag, ifn1 [, ifn2] [...]

  Initialization

"filename" -- A quoted string containing the name of the file to load.

iflag -- Type of the file to load/save. (0 = binary file, Non-zero =
text file)

ifn1, ifn2, ... -- Numbers of tables to load.

  Performance

ktrig -- The trigger signal. Load the file each time it is non-zero.

ftloadk loads a list of tables from a file. (The tables have to be
already allocated though.) The file's format can be binary or text.
Unlike ftload, the loading operation can be repeated numerous times
within the same note by using a trigger signal.

  Warning

The file's format is not compatible with a WAV-file and is not endian-safe.


===========================================================================
ftlptim                                                             *ftlptim*

  Description

Returns the loop segment start-time of a stored function table number.

  Syntax

ftlptim(x) (init-rate args only)

  Performance

Returns the loop segment start-time (in seconds) of stored function
table number x. This reports the duration of the direct recorded attack
and decay parts of a sound sample, prior to its looped segment. Returns
zero (and a warning message) if the sample does not contain loop points.


===========================================================================
ftmorf                                                               *ftmorf*

  Description

Uses an index into a table of ftable numbers to morph between adjacent
tables in the list.This morphed function is written into the table
referenced by iresfn on every k-cycle.

  Syntax

ftmorf kftndx, iftfn, iresfn

  Initialization

iftfn -- The table containing the numbers of any existing tables which
are used for the morphing.

iresfn -- Table number of the morphed function

The length of all the tables in iftfn must equal the length of iresfn.

  Performance

kftndx -- the index into the iftfn table.

If iftfn contains (6, 4, 6, 8, 7, 4):

  * kftndx=4 will write the contents of f7 into iresfn.

  * kftndx=4.5 will write the average of the contents of f7 and f4 into
    iresfn.

  Note

iresfn is only updated if the morfing index changes it's value, if
kftindx is static, no writing to iresfn will occur.


===========================================================================
ftsamplebank                                                   *ftsamplebank*

  Description

Reads a directory for sound files and loads them to a series of GEN01
function tables.

  Syntax

iNumberOfFile ftsamplebank SDirectory, iFirstTableNumber, iTrigger, iSkipTime, iFormat, iChannel,

kNumberOfFile ftsamplebank SDirectory, kFirstTableNumber, kTrigger, kSkipTime, kFormat, kChannel,

  Initialization

SDirectory -- a string that identifies the directory to browse for files

FirstTableNumber -- this sets the number of the first table into which a
soundfile will be loaded

Trigger -- updates the tables when kTrigger is 1

SkipTime -- begin reading at skiptime seconds into the file.

Format -- specifies the audio data-file format:

1 - 8-bit signed character    4 - 16-bit short integers 
2 - 8-bit A-law bytes         5 - 32-bit long integers 
3 - 8-bit U-law bytes         6 - 32-bit floats

Channel -- channel number to read in. 0 denotes read all channels.

If format = 0 the sample format is taken from the soundfile header, or
by default from the CSound -o command-line flag.

  Performance

iNumberOfFile -- the number of tables that have been created

kNumberOfFile -- the number of tables that have been created

  Note

Loading a lot of sound files into function tables at k-rate may cause
some audio dropouts.


===========================================================================
ftsave                                                               *ftsave*

  Description

Save a set of previously-allocated tables to a file.

  Syntax

ftsave "filename", iflag, ifn1 [, ifn2] [...]

  Initialization

"filename" -- A quoted string containing the name of the file to save.

iflag -- Type of the file to save. (0 = binary file, Non-zero = text file)

ifn1, ifn2, ... -- Numbers of tables to save.

  Performance

ftsave saves a list of tables to a file. The file's format can be binary
or text.

  Warning

The file's format is not compatible with a WAV-file and is not endian-safe.


===========================================================================
ftsavek                                                             *ftsavek*

  Description

Save a set of previously-allocated tables to a file.

  Syntax

ftsavek "filename", ktrig, iflag, ifn1 [, ifn2] [...]

  Initialization

"filename" -- A quoted string containing the name of the file to save.

iflag -- Type of the file to save. (0 = binary file, Non-zero = text file)

ifn1, ifn2, ... -- Numbers of tables to save.

  Performance

ktrig -- The trigger signal. Save the file each time it is non-zero.

ftsavek saves a list of tables to a file. The file's format can be
binary or text. Unlike ftsave, the saving operation can be repeated
numerous times within the same note by using a trigger signal.

  Warning

The file's format is not compatible with a WAV-file and is not endian-safe.


===========================================================================
ftsr                                                                   *ftsr*

  Description

Returns the sampling-rate of a stored function table.

  Syntax

ftsr(x) (init-rate args only)

  Performance

Returns the sampling-rate of a GEN01 generated table. The sampling-rate
is determined from the header of the original file. If the original file
has no header or the table was not created by these GEN01, ftsr returns
0. New in Csound version 3.49.


===========================================================================
gain                                                                   *gain*

  Description

Adjusts the amplitude audio signal according to a root-mean-square value.

  Syntax

ares gain asig, krms [, ihp] [, iskip]

  Initialization

ihp (optional, default=10) -- half-power point (in Hz) of a special
internal low-pass filter. The default value is 10.

iskip (optional, default=0) -- initial disposition of internal data
space (see reson). The default value is 0.

  Performance

asig -- input audio signal

gain provides an amplitude modification of asig so that the output ares
has rms power equal to krms. rms and gain used together (and given
matching ihp values) will provide the same effect as balance.


===========================================================================
gainslider                                                       *gainslider*

  Description

This opcode is intended for use to multiply by an audio signal to give a
console mixer like feel. There is no bounds in the source code so you
can for example give higher than 127 values for extra amplitude but
possibly clipped audio.

  Syntax

kout gainslider kindex

  Performance

kindex -- Index value. Nominal range from 0-127. For example a range of
0-152 will give you a range from -∞ to +18.0 dB.

kout -- Scaled output.


===========================================================================
gauss                                                                 *gauss*

  Description

Gaussian distribution random number generator. This is an x-class noise
generator.

  Syntax

ares gauss krange

ires gauss krange

kres gauss krange

  Performance

krange -- the range of the random numbers (-krange to +krange). Outputs
both positive and negative numbers.

gauss returns random numbers following a normal distribution centered
around 0.0 (mu = 0.0) with a variance (sigma) of krange / 3.83. Thus
more than 99.99% of the random values generated are in the range -krange
to +krange. If a mean value different of 0.0 is desired, this mean value
has to be added to the generated numbers (see example below).

For more detailed explanation of these distributions, see:

 1. C. Dodge - T.A. Jerse 1985. Computer music. Schirmer books. pp.265 - 286

 2. D. Lorrain. A panoply of stochastic cannons. In C. Roads, ed. 1989.
    Music machine . Cambridge, Massachusetts: MIT press, pp. 351 - 379.


===========================================================================
gaussi                                                               *gaussi*

  Description

Gaussian distribution random number generator with controlled
interpolation between values. This is an x-class noise generator.

  Syntax

ares gaussi krange, xamp, xcps

ires gaussi krange, xamp, xcps

kres gaussi krange, xamp, xcps

  Performance

krange -- the range of the random numbers (-krange to +krange). Outputs
both positive and negative numbers.

gauss returns random numbers following a normal distribution centered
around 0.0 (mu = 0.0) with a variance (sigma) of krange / 3.83. Thus
more than 99.99% of the random values generated are in the range -krange
to +krange. If a mean value different of 0.0 is desired, this mean value
has to be added to the generated numbers (see example below).

For more detailed explanation of these distributions, see:

 1. C. Dodge - T.A. Jerse 1985. Computer music. Schirmer books. pp.265 - 286

 2. D. Lorrain. A panoply of stochastic cannons. In C. Roads, ed. 1989.
    Music machine . Cambridge, Massachusetts: MIT press, pp. 351 - 379.

xamp -- range over which random numbers are distributed.

xcps -- the frequency which new random numbers are generated.


===========================================================================
gausstrig                                                         *gausstrig*

  Description

Generates random impulses around a certain frequency.

  Syntax

ares gausstrig kamp, kcps, kdev [, imode] [, ifrst1]

kres gausstrig kamp, kcps, kdev [, imode] [, ifrst1]

  Initialization

imode (optional, default=0) -- imode > 0 means better frequency
modulation. If the frequency changes, the delay before the next impulse
is calculed again. With the default mode we have the classic behavior of
the GaussTrig ugen in SuperCollider, where the frequency modulation is
bypassed during the delay time that precedes the next impulse.

ifrst1 (optional, default=0) -- ifrst1 > 0 changes the original behavior
of the GuassTrig ugen. By default, it always generates an impulse in the
very beginning. Otherwise, the first impulse appearance is random and
depends on kcps and kdev parameters.

  Performance

kamp -- amplitude.

kcps -- the mean frequency over which random impulses are distributed.

kdev -- random deviation from mean (0 <= dev < 1).


===========================================================================
gbuzz                                                                 *gbuzz*

  Description

Output is a set of harmonically related cosine partials.

  Syntax

ares gbuzz xamp, xcps, knh, klh, kmul, ifn [, iphs]

  Initialization

ifn -- table number of a stored function containing a cosine wave. A
large table of at least 8192 points is recommended.

iphs (optional, default=0) -- initial phase of the fundamental
frequency, expressed as a fraction of a cycle (0 to 1). A negative value
will cause phase initialization to be skipped. The default value is zero

  Performance

The buzz units generate an additive set of harmonically related cosine
partials of fundamental frequency xcps, and whose amplitudes are scaled
so their summation peak equals xamp. The selection and strength of
partials is determined by the following control parameters:

knh -- total number of harmonics requested. If knh is negative, the
absolute value is used. If knh is zero, a value of 1 is used.

klh -- lowest harmonic present. Can be positive, zero or negative. In
gbuzz the set of partials can begin at any partial number and proceeds
upwards; if klh is negative, all partials below zero will reflect as
positive partials without phase change (since cosine is an even
function), and will add constructively to any positive partials in the set.

kmul -- specifies the multiplier in the series of amplitude
coefficients. This is a power series: if the klhth partial has a
strength coefficient of A, the (klh + n)th partial will have a
coefficient of A * (kmul ** n), i.e. strength values trace an
exponential curve. kmul may be positive, zero or negative, and is not
restricted to integers.

buzz and gbuzz are useful as complex sound sources in subtractive
synthesis. buzz is a special case of the more general gbuzz in which klh
= kmul = 1; it thus produces a set of knh equal-strength harmonic
partials, beginning with the fundamental. (This is a band-limited pulse
train; if the partials extend to the Nyquist, i.e. knh = int (sr / 2 /
fundamental freq.), the result is a real pulse train of amplitude xamp.)

Although both knh and klh may be varied during performance, their
internal values are necessarily integer and may cause “pops” due to
discontinuities in the output. kmul, however, can be varied during
performance to good effect. gbuzz can be amplitude- and/or
frequency-modulated by either control or audio signals.

N.B. This unit has its analog in GEN11, in which the same set of cosines
can be stored in a function table for sampling by an oscillator.
Although computationally more efficient, the stored pulse train has a
fixed spectral content, not a time-varying one as above.


===========================================================================
genarray                                                           *genarray*

  Description

Generate a vector (one-dimensional k-rate or i-rate array) with an
arithmetic sequence.

  Syntax

karray genarray kstart, kens[, inc]

iarray genarray istart, iens[, inc]

  Initialization

istart -- value to place in first element.

iend -- last value to place in array.

inc -- amount to add to previous value (default 1).


===========================================================================
genarray_i                                                       *genarray_i*

  Description

Generate a vector (one-dimensional k-rate) with an arithmetic sequence
at initialisation time.

  Syntax

karray genarray_i istart, iend [,inc]

  Initialization

istart -- value to place in first element.

iend -- last value to place in array.

inc -- amount to add to previous value (default 1).


===========================================================================
gendy                                                                 *gendy*

  Description

Implementation of the Génération Dynamique Stochastique (GENDYN), a
dynamic stochastic approach to waveform synthesis conceived by Iannis
Xenakis.

  Syntax

ares gendy kamp, kampdist, kdurdist, kadpar, kddpar, kminfreq, kmaxfreq, \
           kampscl, kdurscl [, initcps] [, knum]

kres gendy kamp, kampdist, kdurdist, kadpar, kddpar, kminfreq, kmaxfreq, \
           kampscl, kdurscl [, initcps] [, knum]

  Initialization

initcps (optional, default=12) -- max number of control points.

  Performance

kamp -- amplitude.

kampdist -- choice of probability distribution for the next perturbation
of the amplitude of a control point. The valid distributions are:

  * 0 - LINEAR

  * 1 - CAUCHY

  * 2 - LOGIST

  * 3 - HYPERBCOS

  * 4 - ARCSINE

  * 5 - EXPON

  * 6 - SINUS (external k-rate signal)

If kampdist=6, the user can use an external k-rate signal through kadpar.

kdurdist -- choice of distribution for the perturbation of the current
inter control point duration. See kampdist for the valid distributions.
If kdurdist=6, the user can use an external k-rate signal through kddpar.

kadpar -- parameter for the kampdist distribution. Should be in the
range of 0.0001 to 1.

kddpar -- parameter for the kdurdist distribution. Should be in the
range of 0.0001 to 1.

kminfreq -- minimum allowed frequency of oscillation.

kmaxfreq -- maximum allowed frequency of oscillation.

kampscl -- multiplier for the distribution's delta value for amplitude
(1.0 is full range).

kdurscl -- multiplier for the distribution's delta value for duration.

knum (optional, default=initcps) -- current number of utilized control
points.

The waveform is generated by knum - 1 segments and is repeated in the
time. The vertexes (control points) are moved according to a stochastic
action and they are limited within the boundaries of a mirror formed by
an amplitude barrier and a time barrier.

[A repetition of the generated waveform with knum=12.]

A repetition of the generated waveform with knum=12.


===========================================================================
gendyc                                                               *gendyc*

  Description

Implementation with cubic interpolation of the Génération Dynamique
Stochastique (GENDYN), a dynamic stochastic approach to waveform
synthesis conceived by Iannis Xenakis.

  Syntax

ares gendyc kamp, kampdist, kdurdist, kadpar, kddpar, kminfreq, kmaxfreq, \
            kampscl, kdurscl [, initcps] [, knum]

kres gendyc kamp, kampdist, kdurdist, kadpar, kddpar, kminfreq, kmaxfreq, \
            kampscl, kdurscl [, initcps] [, knum]

  Initialization

initcps (optional, default=12) -- max number of control points.

  Performance

kamp -- amplitude.

kampdist -- choice of probability distribution for the next perturbation
of the amplitude of a control point. The valid distributions are:

  * 0 - LINEAR

  * 1 - CAUCHY

  * 2 - LOGIST

  * 3 - HYPERBCOS

  * 4 - ARCSINE

  * 5 - EXPON

  * 6 - SINUS (external k-rate signal)

If kampdist=6, the user can use an external k-rate signal through kadpar.

kdurdist -- choice of distribution for the perturbation of the current
inter control point duration. See kampdist for the valid distributions.
If kdurdist=6, the user can use an external k-rate signal through kddpar.

kadpar -- parameter for the kampdist distribution. Should be in the
range of 0.0001 to 1.

kddpar -- parameter for the kdurdist distribution. Should be in the
range of 0.0001 to 1.

kminfreq -- minimum allowed frequency of oscillation.

kmaxfreq -- maximum allowed frequency of oscillation.

kampscl -- multiplier for the distribution's delta value for amplitude
(1.0 is full range).

kdurscl -- multiplier for the distribution's delta value for duration.

knum (optional, default=initcps) -- current number of utilized control
points.

The waveform is generated by knum - 1 segments and is repeated in the
time. The vertexes (control points) are moved according to a stochastic
action and they are limited within the boundaries of a mirror formed by
an amplitude barrier and a time barrier.


===========================================================================
gendyx                                                               *gendyx*

  Description

gendyx (gendy eXtended) is an implementation of the Génération Dynamique
Stochastique (GENDYN), a dynamic stochastic approach to waveform
synthesis conceived by Iannis Xenakis, using curves instead of segments.

  Syntax

ares gendyx kamp, kampdist, kdurdist, kadpar, kddpar, kminfreq, kmaxfreq, \
            kampscl, kdurscl, kcurveup, kcurvedown [, initcps] [, knum]

kres gendyx kamp, kampdist, kdurdist, kadpar, kddpar, kminfreq, kmaxfreq, \
            kampscl, kdurscl, kcurveup, kcurvedown [, initcps] [, knum]

  Initialization

initcps (optional, default=12) -- max number of control points.

  Performance

kamp -- amplitude.

kampdist -- choice of probability distribution for the next perturbation
of the amplitude of a control point. The valid distributions are:

  * 0 - LINEAR

  * 1 - CAUCHY

  * 2 - LOGIST

  * 3 - HYPERBCOS

  * 4 - ARCSINE

  * 5 - EXPON

  * 6 - SINUS (external k-rate signal)

If kampdist=6, the user can use an external k-rate signal through kadpar.

kdurdist -- choice of distribution for the perturbation of the current
inter control point duration. See kampdist for the valid distributions.
If kdurdist=6, the user can use an external k-rate signal through kddpar.

kadpar -- parameter for the kampdist distribution. Should be in the
range of 0.0001 to 1.

kddpar -- parameter for the kdurdist distribution. Should be in the
range of 0.0001 to 1.

kminfreq -- minimum allowed frequency of oscillation.

kmaxfreq -- maximum allowed frequency of oscillation.

kampscl -- multiplier for the distribution's delta value for amplitude
(1.0 is full range).

kdurscl -- multiplier for the distribution's delta value for duration.

kcurveup -- controls the curve for the increasing amplitudes between two
points; it has to be non negative.

  * 0: step function (like a sample & hold)

  * <1: concave

  * 1: linear (like gendy)

  * >1: convex

kcurvedown -- controls the curve for the decreasing amplitudes between
two points; it has to be non negative.

  * 0: step function

  * <1: convex

  * 1: linear

  * >1: concave

knum (optional, default=initcps) -- current number of utilized control
points.

The waveform is generated by knum - 1 curves and is repeated in the
time. The vertexes (control points) are moved according to a stochastic
action and they are limited within the boundaries of a mirror formed by
an amplitude barrier and a time barrier.

[Extract of a waveform generated with gendyx.]

Extract of a waveform generated with gendyx.


===========================================================================
getcfg                                                               *getcfg*

  Description

Return various configuration settings in Svalue as a string at init time.

  Syntax

Svalue getcfg iopt

  Initialization

iopt -- The parameter to be returned, can be one of:

  * 1: the maximum length of string variables in characters; this is at
    least the value of the -+max_str_len command line option - 1.

===========================================================================
[Note] Note                                              *[Note]        Note*
    In Csound6 there is no maximum string length so the returned value
    is meaningless

  * 2: the input sound file name (-i), or empty if there is no input file

  * 3: the output sound file name (-o), or empty if there is no output file

  * 4: return "1" if real time audio input or output is being used, and
    "0" otherwise

  * 5: return "1" if running in beat mode (-t command line option), and
    "0" otherwise

  * 6: the host operating system name

  * 7: return "1" if a callback function for the chnrecv and chnsend
    opcodes has been set, and "0" otherwise (which means these opcodes
    do nothing)


===========================================================================
getrow                                                               *getrow*

  Description

Gets a given row from a 2-dimensional array. The output is an 1-d array
with the contents of the requested row

  Syntax

kout[] getrowkin[],krow

  Performance

kout[] -- output array containing the extracted row. It will be created
if it does not exist.

kin[] -- input 2-dimensional array.

krow -- row to be extracted.


===========================================================================
getseed                                                             *getseed*

  Description

Returns the global seed value used for all x-class noise generators.

  Syntax

ians getseed

kans getseed

  Performance

Reads the global seed value of the internal pseudo-random number generator.


===========================================================================
gogobel                                                             *gogobel*

  Description

Audio output is a tone related to the striking of a cow bell or similar.
The method is a physical model developed from Perry Cook, but re-coded
for Csound.

  Syntax

ares gogobel kamp, kfreq, ihrd, ipos, imp, kvibf, kvamp, ivfn

  Initialization

ihrd -- the hardness of the stick used in the strike. A range of 0 to 1
is used. 0.5 is a suitable value.

ipos -- where the block is hit, in the range 0 to 1.

imp -- a table of the strike impulses. The file marmstk1.wav is a
suitable function from measurements and can be loaded with a GEN01
table. It is also available at
ftp://ftp.cs.bath.ac.uk/pub/dream/documentation/sounds/modelling/.

ivfn -- shape of vibrato, usually a sine table, created by a function.

  Performance

A note is played on a cowbell-like instrument, with the arguments as below.

kamp -- Amplitude of note.

kfreq -- Frequency of note played.

kvibf -- frequency of vibrato in Hertz. Suggested range is 0 to 12

kvamp -- amplitude of the vibrato


===========================================================================
goto                                                                   *goto*

  Description

Transfer control to label on every pass. (Combination of igoto and kgoto)

  Syntax

goto label

where label is in the same instrument block and is not an expression.

  Note
Using goto not as part of an if statement (as in: goto end), will cause
initialization to be skipped on all the code the goto jumps over. In
performance, leaving some opcodes uninitialized will cause deletion of
the note/event. In these cases, using kgoto (as in: kgoto end) might be
preferred."


===========================================================================
grain                                                                 *grain*

  Description

Generates granular synthesis textures.

  Syntax

ares grain xamp, xpitch, xdens, kampoff, kpitchoff, kgdur, igfn, \
      iwfn, imgdur [, igrnd]

  Initialization

igfn -- The ftable number of the grain waveform. This can be just a sine
wave or a sampled sound.

iwfn -- Ftable number of the amplitude envelope used for the grains (see
also GEN20).

imgdur -- Maximum grain duration in seconds. This is the biggest value
to be assigned to kgdur.

igrnd (optional) -- if non-zero, turns off grain offset randomness. This
means that all grains will begin reading from the beginning of the igfn
table. If zero (the default), grains will start reading from random igfn
table positions.

  Performance

xamp -- Amplitude of each grain.

xpitch -- Grain pitch. To use the original frequency of the input sound,
use the formula:

   sndsr / ftlen(igfn)

where sndsr is the original sample rate of the igfn sound.

xdens -- Density of grains measured in grains per second. If this is
constant then the output is synchronous granular synthesis, very similar
to fof. If xdens has a random element (like added noise), then the
result is more like asynchronous granular synthesis.

kampoff -- Maximum amplitude deviation from xamp. This means that the
maximum amplitude a grain can have is xamp + kampoff and the minimum is
xamp. If kampoff is set to zero then there is no random amplitude for
each grain.

kpitchoff -- Maximum pitch deviation from xpitch in Hz. Similar to kampoff.

kgdur -- Grain duration in seconds. The maximum value for this should be
declared in imgdur. If kgdur at any point becomes greater than imgdur,
it will be truncated to imgdur.

The grain generator is based primarily on work and writings of Barry
Truax and Curtis Roads.


===========================================================================
grain2                                                               *grain2*

  Description

Generate granular synthesis textures. grain2 is simpler to use, but
grain3 offers more control.

  Syntax

ares grain2 kcps, kfmd, kgdur, iovrlp, kfn, iwfn [, irpow] \
      [, iseed] [, imode]

  Initialization

iovrlp -- (fixed) number of overlapping grains.

iwfn -- function table containing window waveform (Use GEN20 to
calculate iwfn).

irpow (optional, default=0) -- this value controls the distribution of
grain frequency variation. If irpow is positive, the random distribution
(x is in the range -1 to 1) is

abs(x) ^ ((1 / irpow) - 1);

for negative irpow values, it is

(1 - abs(x)) ^ ((-1 / irpow) - 1)

Setting irpow to -1, 0, or 1 will result in uniform distribution (this
is also faster to calculate). The image below shows some examples for
irpow. The default value of irpow is 0.

[A graph of distributions for different values of irpow.]

A graph of distributions for different values of irpow.

iseed (optional, default=0) -- seed value for random number generator
(positive integer in the range 1 to 2147483646 (2^31 - 2)). Zero or
negative value seeds from current time (this is also the default).

imode (optional default=0) -- sum of the following values:

  * 8: interpolate window waveform (slower).

  * 4: do not interpolate grain waveform (fast, but lower quality).

  * 2: grain frequency is continuously modified by kcps and kfmd (by
    default, each grain keeps the frequency it was launched with). This
    may be slower at high control rates.

  * 1: skip initialization.

  Performance

ares -- output signal.

kcps -- grain frequency in Hz.

kfmd -- random variation (bipolar) in grain frequency in Hz.

kgdur -- grain duration in seconds. kgdur also controls the duration of
already active grains (actually the speed at which the window function
is read). This behavior does not depend on the imode flags.

kfn -- function table containing grain waveform. Table number can be
changed at k-rate (this is useful to select from a set of band-limited
tables generated by GEN30, to avoid aliasing).

  Note

grain2 internally uses the same random number generator as rnd31. So
reading its documentation is also recommended.


===========================================================================
grain3                                                               *grain3*

  Description

Generate granular synthesis textures. grain2 is simpler to use but
grain3 offers more control.

  Syntax

ares grain3 kcps, kphs, kfmd, kpmd, kgdur, kdens, imaxovr, kfn, iwfn, \
      kfrpow, kprpow [, iseed] [, imode]

  Initialization

imaxovr -- maximum number of overlapping grains. The number of overlaps
can be calculated by (kdens * kgdur); however, it can be overestimated
at no cost in rendering time, and a single overlap uses (depending on
system) 16 to 32 bytes of memory.

iwfn -- function table containing window waveform (Use GEN20 to
calculate iwfn).

iseed (optional, default=0) -- seed value for random number generator
(positive integer in the range 1 to 2147483646 (2^31 - 2)). Zero or
negative value seeds from current time (this is also the default).

imode (optional, default=0) -- sum of the following values:

  * 64: synchronize start phase of grains to kcps.

  * 32: start all grains at integer sample location. This may be faster
    in some cases, however it also makes the timing of grain envelopes
    less accurate.

  * 16: do not render grains with start time less than zero. (see the
    image below; this option turns off grains marked with red on the image).

  * 8: interpolate window waveform (slower).

  * 4: do not interpolate grain waveform (fast, but lower quality).

  * 2: grain frequency is continuously modified by kcps and kfmd (by
    default, each grain keeps the frequency it was launched with). This
    may be slower at high control rates. It also controls phase
    modulation (kphs).

  * 1: skip initialization.

[A diagram showing grains with a start time less than zero in red.]

A diagram showing grains with a start time less than zero in red.

  Performance

ares -- output signal.

kcps -- grain frequency in Hz.

kphs -- grain phase. This is the location in the grain waveform table,
expressed as a fraction (between 0 to 1) of the table length.

kfmd -- random variation (bipolar) in grain frequency in Hz.

kpmd -- random variation (bipolar) in start phase.

kgdur -- grain duration in seconds. kgdur also controls the duration of
already active grains (actually the speed at which the window function
is read). This behavior does not depend on the imode flags.

kdens -- number of grains per second.

kfrpow -- this value controls the distribution of grain frequency
variation. If kfrpow is positive, the random distribution (x is in the
range -1 to 1) is

abs(x) ^ ((1 / kfrpow) - 1)

; for negative kfrpow values, it is

(1 - abs(x)) ^ ((-1 / kfrpow) - 1)

Setting kfrpow to -1, 0, or 1 will result in uniform distribution (this
is also faster to calculate). The image below shows some examples for
kfrpow. The default value of kfrpow is 0.

[A graph of distributions for different values of kfrpow.]

A graph of distributions for different values of kfrpow.

kprpow -- distribution of random phase variation (see kfrpow). Setting
kphs and kpmd to 0.5, and kprpow to 0 will emulate grain2.

kfn -- function table containing grain waveform. Table number can be
changed at k-rate (this is useful to select from a set of band-limited
tables generated by GEN30, to avoid aliasing).

  Note

grain3 internally uses the same random number generator as rnd31. So
reading its documentation is also recommended.


===========================================================================
granule                                                             *granule*

  Description

The granule unit generator is more complex than grain, but does add new
possibilities.

granule is a Csound unit generator which employs a wavetable as input to
produce granularly synthesized audio output. Wavetable data may be
generated by any of the GEN subroutines such as GEN01 which reads an
audio data file into a wavetable. This enable a sampled sound to be used
as the source for the grains. Up to 128 voices are implemented
internally. The maximum number of voices can be increased by redefining
the variable MAXVOICE in the grain4.h file. granule has a build-in
random number generator to handle all the random offset parameters.
Thresholding is also implemented to scan the source function table at
initialization stage. This facilitates features such as skipping silence
passage between sentences.

The characteristics of the synthesis are controlled by 22 parameters.
xamp is the amplitude of the output and it can be either audio rate or
control rate variable.

  Syntax

ares granule xamp, ivoice, iratio, imode, ithd, ifn, ipshift, igskip, \
      igskip_os, ilength, kgap, igap_os, kgsize, igsize_os, iatt, idec \
      [, iseed] [, ipitch1] [, ipitch2] [, ipitch3] [, ipitch4] [, ifnenv]

  Initialization

ivoice -- number of voices.

iratio -- ratio of the speed of the gskip pointer relative to output
audio sample rate. eg. 0.5 will be half speed.

imode -- +1 grain pointer move forward (same direction of the gskip
pointer), -1 backward (oppose direction to the gskip pointer) or 0 for
random.

ithd -- threshold, if the sampled signal in the wavetable is smaller
then ithd, it will be skipped.

ifn -- function table number of sound source.

ipshift -- pitch shift control. If ipshift is 0, pitch will be set
randomly up and down an octave. If ipshift is 1, 2, 3 or 4, up to four
different pitches can be set amount the number of voices defined in
ivoice. The optional parameters ipitch1, ipitch2, ipitch3 and ipitch4
are used to quantify the pitch shifts.

igskip -- initial skip from the beginning of the function table in sec.

igskip_os -- gskip pointer random offset in sec, 0 will be no offset.

ilength -- length of the table to be used starting from igskip in sec.

igap_os -- gap random offset in % of the gap size, 0 gives no offset.

igsize_os -- grain size random offset in % of grain size, 0 gives no
offset.

iatt -- attack of the grain envelope in % of grain size.

idec -- decade of the grain envelope in % of grain size.

iseed (optional, default=0.5) -- seed for the random number generator.

ipitch1, ipitch2, ipitch3, ipitch4 (optional, default=1) -- pitch shift
parameter, used when ipshift is set to 1, 2, 3 or 4. Time scaling
technique is used in pitch shift with linear interpolation between data
points. Default value is 1, the original pitch.

ifnenv (optional, default=0) -- function table number to be used to
generate the shape of the envelope.

  Performance

xamp -- amplitude.

kgap -- gap between grains in sec.

kgsize -- grain size in sec.


===========================================================================
guiro                                                                 *guiro*

  Description

guiro is a semi-physical model of a guiro sound. It is one of the PhISEM
percussion opcodes. PhISEM (Physically Informed Stochastic Event
Modeling) is an algorithmic approach for simulating collisions of
multiple independent sound producing objects.

  Syntax

ares guiro kamp, idettack [, inum] [, idamp] [, imaxshake] [, ifreq] [, ifreq1]

  Initialization

idettack -- period of time over which all sound is stopped

inum (optional) -- The number of beads, teeth, bells, timbrels, etc. If
zero, the default value is 128.

idamp (optional) -- the damping factor of the instrument. Not used.

imaxshake (optional, default=0) -- amount of energy to add back into the
system. The value should be in range 0 to 1.

ifreq (optional) -- the main resonant frequency. The default value is
2500 Hz.

ifreq1 (optional) -- the first resonant frequency. Default value here is
4000 Hz

  Performance

kamp -- Amplitude of output. Note: As these instruments are stochastic,
this is only an approximation.


===========================================================================
harmon                                                               *harmon*

  Description

Analyze an audio input and generate harmonizing voices in synchrony.

  Syntax

ares harmon asig, kestfrq, kmaxvar, kgenfreq1, kgenfreq2, imode, \
      iminfrq, iprd

  Initialization

imode -- interpreting mode for the generating frequency inputs
kgenfreq1, kgenfreq2. 0: input values are ratios with respect to the
audio signal analyzed frequency. 1: input values are the actual
requested frequencies in Hz.

iminfrq -- the lowest expected frequency (in Hz) of the audio input.
This parameter determines how much of the input is saved for the running
analysis, and sets a lower bound on the internal pitch tracker.

iprd -- period of analysis (in seconds). Since the internal pitch
analysis can be time-consuming, the input is typically analyzed only
each 20 to 50 milliseconds.

  Performance

kestfrq -- estimated frequency of the input.

kmaxvar -- the maximum variance (expects a value betwee 0 and 1).

kgenfreq1 -- the first generated frequency.

kgenfreq2 -- the second generated frequency.

This unit is a harmonizer, able to provide up to two additional voices
with the same amplitude and spectrum as the input. The input analysis is
assisted by two things: an input estimated frequency kestfrq (in Hz),
and a fractional maximum variance kmaxvar about that estimate which
serves to limit the size of the search. Once the real input frequency is
determined, the most recent pulse shape is used to generate the other
voices at their requested frequencies.

The three frequency inputs can be derived in various ways from a score
file or MIDI source. The first is the expected pitch, with a variance
parameter allowing for inflections or inaccuracies; if the expected
pitch is zero the harmonizer will be silent. The second and third
pitches control the output frequencies; if either is zero the harmonizer
will output only the non-zero request; if both are zero the harmonizer
will be silent. When the requested frequency is higher than the input,
the process requires additional computation due to overlapped output
pulses. This is currently limited for efficiency reasons, with the
result that only one voice can be higher than the input at any one time.

This unit is useful for supplying a background chorus effect on demand,
or for correcting the pitch of a faulty input vocal. There is
essentially no delay between input and output. Output includes only the
generated parts, and does not include the input.


===========================================================================
harmon2                                                             *harmon2*

  Description

Generate harmonizing voices with formants preserved.

  Syntax

ares harmon2 asig, koct, kfrq1, kfrq2, icpsmode, ilowest[, ipolarity]

ares harmon3 asig, koct, kfrq1, \
    kfrq2, kfrq3, icpsmode, ilowest[, ipolarity]

ares harmon4 asig, koct, kfrq1, \
    kfrq2, kfrq3, kfrq4, icpsmode, ilowest[, ipolarity]

  Initialization

icpsmode -- interpreting mode for the generating frequency inputs kfrq1,
kfrq2, kfrq3 and kfrq4: 0: input values are ratios w.r.t. the cps
equivalent of koct. 1: input values are the actual requested frequencies
in cps.

ilowest -- lowest value of the koct input for which harmonizing voices
will be generated.

ipolarity -- polarity of asig input, 1 = positive glottal pulses, 0 =
negative. Default is 1.

  Performance

Harmon2, harmon3 and harmon4 are high-performance harmonizers, able to
provide up to four pitch-shifted copies of the input asig with spectral
formants preserved. The pitch-shifting algorithm requires an accurate
running estimate (koct, in decimal oct units) of the pitched content of
asig, normally gained from an independent pitch tracker such as
specptrk. The algorithm then isolates the most recent full pulse within
asig, and uses this to generate the other voices at their required pulse
rates.

If the frequency (or ratio) presented to kfrq1, kfrq2, kfrq3 or kfrq4 is
zero, then no signal is generated for that voice. If any of them is
non-zero, but the koct input is below the value ilowest, then that voice
will output a direct copy of the input asig. As a consequence, the data
arriving at the k-rate inputs can variously cause the generated voices
to be turned on or off, to pass a direct copy of a non-voiced fricative
source, or to harmonize the source according to some constructed
algorithm. The transition from one mode to another is cross-faded,
giving seemless alternating between voiced (harmonized) and non-voiced
fricatives during spoken or sung input.

harmon2, harmon3, harmon4 are especially matched to the output of
specptrk. The latter generates pitch data in decimal octave format; it
also emits its base value if no pitch is identified (as in fricative
noise) and emits zero if the energy falls below a threshold, so that
harmon2, harmon3, harmon4 can be set to pass the direct signal in both
cases. Of course, any other form of pitch estimation could also be used.
Since pitch trackers usually incur a slight delay for accurate
estimation (for specptrk the delay is printed by the spectrum unit), it
is normal to delay the audio signal by the same amount so that harmon2,
harmon3, harmon4 can work from a fully concurrent estimate.


===========================================================================
hdf5read                                                           *hdf5read*

  Description

hdf5read reads N signals and arrays from a specified hdf5 file.

  Syntax

xout1[, xout2, xout3, ..., xoutN] hdf5read ifilename, ivariablename1[, ivariablename2, ivariablename3, ..., ivariablenameN]

  Initialization

ifilename -- the hdf5 file's name (in double-quotes).

ivariablename1[, ivariablename2, ivariablename3, ..., ivariablenameN] --
the names of the datasets (in double-quotes) to be read from the hdf5 file.

  Performance

xout1,... xoutN -- The specified types of variables that the hdf5
datasets are to be read as. Datasets with a rank larger than 1 must be
read as arrays, i-rate signals must also be read as i-rate signals.
Other than these restrictions datasets may be read as any type of array
or signal. When reading has reached the end of a dataset it no longer
outputs any new values.


===========================================================================
hdf5write                                                         *hdf5write*

  Description

hdf5write writes N signals and arrays to a specified hdf5 file.

  Syntax

hdf5write ifilename, xout1[, xout2, xout3, ..., xoutN]

  Initialization

ifilename -- the hdf5 file's name (in double-quotes). If the file does
not exist it will be created.

  Performance

xout1,... xoutN -- signals or arrays to be written to the hdf5 file.
This opcode accepts i-rate, k-rate, a-rate signals or i-rate, k-rate,
a-rate arrays of any dimension. These signals or arrays are written to a
dataset within the hdf5 file using the same variable name as in Csound.
For example, if the Csound variable is called 'ksignal', then the name
of the hdf5 dataset is 'ksignal'. Any number and multiple types of
datasets may be written at a time.


===========================================================================
hilbert                                                             *hilbert*

  Description

An IIR implementation of a Hilbert transformer.

  Syntax

ar1, ar2 hilbert asig

  Performance

asig -- input signal

ar1 -- sine output of asig

ar2 -- cosine output of asig

hilbert is an IIR filter based implementation of a broad-band 90 degree
phase difference network. The input to hilbert is an audio signal, with
a frequency range from 15 Hz to 15 kHz. The outputs of hilbert have an
identical frequency response to the input (i.e. they sound the same),
but the two outputs have a constant phase difference of 90 degrees, plus
or minus some small amount of error, throughout the entire frequency
range. The outputs are in quadrature.

hilbert is useful in the implementation of many digital signal
processing techniques that require a signal in phase quadrature. ar1
corresponds to the cosine output of hilbert, while ar2 corresponds to
the sine output. The two outputs have a constant phase difference
throughout the audio range that corresponds to the phase relationship
between cosine and sine waves.

Internally, hilbert is based on two parallel 6th-order allpass filters.
Each allpass filter implements a phase lag that increases with
frequency; the difference between the phase lags of the parallel allpass
filters at any given point is approximately 90 degrees.

Unlike an FIR-based Hilbert transformer, the output of hilbert does not
have a linear phase response. However, the IIR structure used in hilbert
is far more efficient to compute, and the nonlinear phase response can
be used in the creation of interesting audio effects, as in the second
example below.


===========================================================================
hrtfearly                                                         *hrtfearly*

  Description

This opcode essentially nests the hrtfmove opcode in an image model for
a user-definable shoebox-shaped room. A default room can be selected, or
advanced room parameters can be used. Room surfaces can be controlled
with high and low-frequency absorption coefficients and gain factors of
a three-band equaliser.

Although valid as a stand alone opcode, hrtfearly is designed to work
with hrtfreverb to provide spatially accurate, dynamic binaural
reverberation. A number of sources can be processed dynamically using a
number of hrtfearly instances. All can then be processed with one
instance of hrtfreverb.

  Syntax

aleft, aright, irt60low, irt60high, imfp hrtfearly asrc, ksrcx, ksrcy, ksrcz, klstnrx, klstnry, klstnrz, \
      ifilel, ifiler, idefroom [,ifade, isr, iorder, ithreed, kheadrot, iroomx, iroomy, iroomz, iwallhigh, \
      iwalllow, iwallgain1, iwallgain2, iwallgain3, ifloorhigh, ifloorlow, ifloorgain1, ifloorgain2, \
      ifloorgain3, iceilinghigh, iceilinglow, iceilinggain1, iceilinggain2, iceilinggain3]

  Initialization

ifilel - left HRTF spectral data file.

ifiler - right HRTF spectral data file.

  Note

Spectral datafiles (based on the MIT HRTF database) are available in 3
different sampling rates: 44.1, 48 and 96 kHz and are labelled
accordingly. Input and processing sr should match datafile sr. Files
should be in the current directory or the SADIR (see Environment
Variables).

  Note

HRTF Data files for use with hrtfmove, hrtfmove2, hrtfstat, hrtfearly,
hrtfreverb were updated for Csound 5.15 and later (the code was updated
and is more efficient). Old datafiles are now deprecated.

idefroom - default room, medium (1: 10*10*3), small (2: 3*4*3) or large
(3: 20*25*7). Wall details (high coef, low coef, gain1, gain2, gain3):
.3, .1, .75, .95, .9. Floor: .6, .1, .95, .6, .35. Ceiling: .2, .1, 1,
1, 1. If 0 is entered, optional room parameters will be read.

ifade - optional, number of processing buffers for phase change
crossfade (default 8). Legal range is 1-24. See hrtfmove.

isr - optional, default 44.1kHz, legal values: 44100, 48000 and 96000.

iorder - optional, order of images processed: higher order: more
reflections. Defaults to 1, legal range: 0-4.

ithreed - optional, process image sources in three dimensions (1) or two
(0: default).

iroomx - optional, x room size in metres, will be read if no valid
default room is entered (all below parameters behave similarly). Minimum
room size is 2*2*2.

iroomy - optional, y room size.

iroomz - optional, z room size.

iwallhigh - optional, high frequency wall absorption coefficient (all 4
walls are assumed identical). Absorption coefficients will affect reverb
time output.

iwalllow - optional, low frequency wall absorption coefficient.

iwallgain1 - optional, gain on filter centred at 250 Hz (all filters
have a Q implying 4 octaves).

iwallgain2 - optional, as above, centred on 1000 Hz.

iwallgain3 - optional, as above, centred on 4000 Hz.

ifloorhigh, ifloorlow, ifloorgain1, ifloorgain2, ifloorgain3 - as above
for floor.

iceilinghigh, iceilinglow, iceilinggain1, iceilinggain2, iceilinggain3 -
as above for ceiling.

ksrcx source x location, must be 10 cm inside room. Also, near-field
HRTFs are not processed, so source will not change spatially within a 45
cm radius of the listener. These restrictions also apply to location
parameters below.

ksrcy source y location.

ksrcz source z location.

klstnrx, klstnry, klstnrz listener location, as above.

kheadrot - optional, angular value for head rotation.

asrc - Input/source signal.

irt60low - suggested low frequency reverb time for later binaural reverb.

irt60high - as above, for high frequency.

imfp - mean free path of room, to be used with later reverb.


===========================================================================
hrtfmove                                                           *hrtfmove*

  Description

This opcode takes a source signal and spatialises it in the 3
dimensional space around a listener by convolving the source with stored
head related transfer function (HRTF) based filters.

  Syntax

aleft, aright hrtfmove asrc, kAz, kElev, ifilel, ifiler [, imode, ifade, isr]

  Initialization

ifilel -- left HRTF spectral data file

ifiler -- right HRTF spectral data file

  Note

Spectral datafiles (based on the MIT HRTF database) are available in 3
different sampling rates: 44.1, 48 and 96 khz and are labelled
accordingly. Input and processing sr should match datafile sr. Files
should be in the current directory or the SADIR (see Environment
Variables).

  Note

HRTF Data files for use with hrtfmove, hrtfmove2, hrtfstat, hrtfearly,
hrtfreverb were updated for Csound 5.15 and later (the code was updated
and is more efficient). Old datafiles are now deprecated.

imode -- optional, default 0 for phase truncation, 1 for minimum phase

ifade -- optional, number of processing buffers for phase change
crossfade (default 8). Legal range is 1-24. A low value is recommended
for complex sources (4 or less: a higher value may make the crossfade
audible), a higher value (8 or more: a lower value may make the
inconsistency when the filter changes phase values audible) for
narrowband sources. Does not effect minimum phase processing.

  Note

Ocassionally fades may overlap (when unnaturally fast/complex
trajectories are requested). In this case, a warning will be printed.
Use a smaller crossfade or slightly change trajectory to avoid any
possible inconsistencies that may arise.

isr - optional, default 44.1kHz, legal values: 44100, 48000 and 96000.

kAz -- azimuth value in degrees. Positive values represent position on
the right, negative values are positions on the left.

kElev -- elevation value in degrees. Positive values represent position
above horizontal, negative values are positions below horizontal (min -40).

Artifact-free user-defined trajectories are made possible using an
interpolation algorithm based on spectral magnitude interpolation and
phase truncation. Crossfades are implemented to minimise/eliminate any
inconsistencies caused by updating phase values. These crossfades are
performed over a user definable number of convolution processing
buffers. Complex sources may only need to crossfade over 1 buffer;
narrow band sources may need several. The opcode also offers minimum
phase based processing, a more traditional and complex method. In this
mode, the hrtf filters used are reduced to minimum phase representations
and the interpolation process then uses the relationship between minimum
phase magnitude and phase spectra. Interaural time difference, which is
inherent to the phase truncation process, is reintroduced in the minimum
phase process using variable delay lines.


===========================================================================
hrtfmove2                                                         *hrtfmove2*

  Description

This opcode takes a source signal and spatialises it in the 3
dimensional space around a listener using head related transfer function
(HRTF) based filters.

  Syntax

aleft, aright hrtfmove2 asrc, kAz, kElev, ifilel, ifiler [,ioverlap, iradius, isr]

  Initialization

ifilel -- left HRTF spectral data file

ifiler -- right HRTF spectral data file

  Note

Spectral datafiles (based on the MIT HRTF database) are available in 3
different sampling rates: 44.1, 48 and 96 khz and are labelled
accordingly. Input and processing sr should match datafile sr. Files
should be in the current directory or the SADIR (see Environment
Variables).

  Note

HRTF Data files for use with hrtfmove, hrtfmove2, hrtfstat, hrtfearly,
hrtfreverb were updated for Csound 5.15 and later (the code was updated
and is more efficient). Old datafiles are now deprecated.

ioverlap -- optional, number of overlaps for STFT processing (default
4). See STFT section of manual.

iradius -- optional, head radius used for phase spectra calculation in
centimeters (default 9.0)

isr - optional, default 44.1kHz, legal values: 44100, 48000 and 96000.

  Performance

asrc -- Input/source signal.

kAz -- azimuth value in degrees. Positive values represent position on
the right, negative values are positions on the left.

kElev -- elevation value in degrees. Positive values represent position
above horizontal, negative values are positions below horizontal (min -40).

Artifact-free user-defined trajectories are made possible using an
interpolation algorithm based on spectral magnitude interpolation and a
derived phase spectrum based on the Woodworth spherical head model.
Accuracy is increased for the data set provided by extracting and
applying a frequency dependent scaling factor to the phase spectra,
leading to a more precise low frequency interaural time difference.
Users can control head radius for the phase derivation, allowing a crude
level of individualisation. The dynamic source version of the opcode
uses a Short Time Fourier Transform algorithm to avoid artefacts caused
by derived phase spectra changes. STFT processing means this opcode is
more computationally intensive than hrtfmove using phase truncation, but
phase is constantly updated by hrtfmove2.


===========================================================================
hrtfreverb                                                       *hrtfreverb*

  Description

A frequency-dependent, efficient reverberant field is created based on
low and high frequency desired reverb times. The opcode is designed to
work with hrtfearly, ideally using its outputs as inputs. However,
hrtfreverb can be used as a standalone tool. Stability is enforced.

It is, however, designed for use with hrtfearly to provide spatially
accurate reverberation with user definable source trajectories. Accurate
interaural coherence is also provided.

  Syntax

aleft, aright, idel hrtfreverb asrc, ilowrt60, ihighrt60, ifilel, ifiler [,isr, imfp, iorder]

  Initialization

ilowrt60 - low frequency reverb time.

ihighrt60 - high frequency reverb time.

ifilel - left HRTF spectral data file.

ifiler - right HRTF spectral data file.

  Note

Spectral datafiles (based on the MIT HRTF database) are available in 3
different sampling rates: 44.1, 48 and 96 kHz and are labelled
accordingly. Input and processing sr should match datafile sr. Files
should be in the current directory or the SADIR (see Environment
Variables).

  Note

HRTF Data files for use with hrtfmove, hrtfmove2, hrtfstat, hrtfreverb,
hrtfreverb were updated for Csound 5.15 and later (the code was updated
and is more efficient). Old datafiles are now deprecated.

isr - optional, default 44.1kHz, legal values: 44100, 48000 and 96000.

imfp - optional, mean free path, defaults to that of a medium room. If
used with hrtfearly, the mean free path of the room can be used to
calculate the appropriate delay for the later reverb. Legal range: the
mean free path of the smallest room allowed by hrtfearly (0.003876) 1.

iorder - optional, order of early reflection processing. If used with
hrtfearly, the order of early reflections can be used to calculate the
appropriate delay on the later reverb.

asrc - Input/source signal.

idel - if used with hrtfearly, the appropriate delay for the later
reverb, based on the room and order of processing.


===========================================================================
hrtfstat                                                           *hrtfstat*

  Description

This opcode takes a source signal and spatialises it in the 3
dimensional space around a listener using head related transfer function
(HRTF) based filters. It produces a static output (azimuth and elevation
parameters are i-rate), because a static source allows much more
efficient processing than hrtfmove and hrtfmove2,.

  Syntax

      aleft, aright hrtfstat asrc, iAz, iElev, ifilel, ifiler [,iradius, isr]

  Initialization

iAz -- azimuth value in degrees. Positive values represent position on
the right, negative values are positions on the left.

iElev -- elevation value in degrees. Positive values represent position
above horizontal, negative values are positions below horizontal (min -40).

ifilel -- left HRTF spectral data file

ifiler -- right HRTF spectral data file

  Note

Spectral datafiles (based on the MIT HRTF database) are available in 3
different sampling rates: 44.1, 48 and 96 khz and are labelled
accordingly. Input and processing sr should match datafile sr. Files
should be in the current directory or the SADIR (see Environment
Variables).

  Note

HRTF Data files for use with hrtfmove, hrtfmove2, hrtfstat, hrtfearly,
hrtfreverb were updated for Csound 5.15 and later (the code was updated
and is more efficient). Old datafiles are now deprecated.

iradius -- optional, head radius used for phase spectra calculation in
centimeters (default 9.0)

isr - optional (default 44.1kHz). Legal values are 44100, 48000 and 96000.

  Performance

Artifact-free user-defined static spatialisation is made possible using
an interpolation algorithm based on spectral magnitude interpolation and
a derived phase based on the Woodworth spherical head model. Accuracy is
increased for the data set provided by extracting and applying a
frequency dependent scaling factor to the phase spectra, leading to a
more precise low frequency interaural time difference. Users can control
head radius for the phase derivation, allowing a crude level of
individualisation. The static source version of the opcode uses overlap
add convolution (it does not need STFT processing, see hrtfmove2), and
is thus considerably more efficient than hrtfmove2 or hrtfmove, but
cannot generate moving sources.


===========================================================================
hsboscil                                                           *hsboscil*

  Description

An oscillator which takes tonality and brightness as arguments, relative
to a base frequency.

  Syntax

ares hsboscil kamp, ktone, kbrite, ibasfreq, iwfn, ioctfn \
               [, ioctcnt] [, iphs]

  Initialization

ibasfreq -- base frequency to which tonality and brighness are relative

iwfn -- function table of the waveform, usually a sine

ioctfn -- function table used for weighting the octaves, usually
something like:

f1 0  1024  -19  1  0.5  270  0.5

ioctcnt (optional) -- number of octaves used for brightness blending.
Must be in the range 2 to 10. Default is 3.

iphs (optional, default=0) -- initial phase of the oscillator. If iphs =
-1, initialization is skipped.

  Performance

kamp -- amplitude of note

ktone -- cyclic tonality parameter relative to ibasfreq in logarithmic
octave, range 0 to 1, values > 1 can be used, and are internally reduced
to frac(ktone).

kbrite -- brightness parameter relative to ibasfreq, achieved by
weighting ioctcnt octaves. It is scaled in such a way, that a value of 0
corresponds to the orignal value of ibasfreq, 1 corresponds to one
octave above ibasfreq, -2 corresponds to two octaves below ibasfreq,
etc. kbrite may be fractional.

hsboscil takes tonality and brightness as arguments, relative to a base
frequency (ibasfreq). Tonality is a cyclic parameter in the logarithmic
octave, brightness is realized by mixing multiple weighted octaves. It
is useful when tone space is understood in a concept of polar coordinates.

Making ktone a line, and kbrite a constant, produces Risset's glissando.

Oscillator table iwfn is always read interpolated. Performance time
requires about ioctcnt * oscili.


===========================================================================
hvs1                                                                   *hvs1*

  Description

hvs1 allows one-dimensional Hyper Vectorial Synthesis (HVS) controlled
by externally-updated k-variables.

  Syntax

hvs1 kx, inumParms, inumPointsX, iOutTab, iPositionsTab, iSnapTab [, iConfigTab]

  Initialization

inumParms - number of parameters controlled by the HVS. Each HVS
snapshot is made up of inumParms elements.

inumPointsX - number of points that each dimension of the HVS cube (or
square in case of two-dimensional HVS; or line in case of
one-dimensional HVS) is made up.

iOutTab - number of the table receiving the set of output-parameter
instant values of the HVS. The total amount of parameters is defined by
the inumParms argument.

iPositionsTab – a table filled with the individual positions of
snapshots in the HVS matrix (see below for more information).

iSnapTab – a table filled with all the snapshots. Each snapshot is made
up of a set of parameter values. The amount of elements contained in
each snapshots is specified by the inumParms argument. The set of
elements of each snapshot follows (and is adjacent) to the previous one
in this table. So the total size of this table should be >= to inumParms
multiplied the number of snapshots you intend to store for the HVS.

iConfigTab – (optional) a table containing the behavior of the HVS for
each parameter. If the value of iConfigTab is zero (default), this
argument is ignored, meaning that each parameter is treated with linear
interpolation by the HVS. If iConfigTab is different than zero, then it
must refer to an existing table whose contents are in its turn referring
to a particolar kind of interpolation. In this table, a value of -1
indicates that corresponding parameter is leaved unchanged (ignored) by
the HVS; a value of zero indicates that corresponding parameter is
treated with linear-interpolation; each other values must be integer
numbers indicating an existing table filled with a shape which will
determine the kind of special interpolation to be used (table-based
interpolation).

  Performance

kx - these are externally-modified variables which controls the motion
of the pointer in the HVS matrix cube (or square or line in case of HVS
matrices made up of less than 3 dimensions). The range of these input
arguments must be 0 to 1.

Hyper Vectorial Synthesis is a technique that allows control of a huge
set of parameters by using a simple and global approach. The key
concepts of the HVS are:

The set of HVS parameters, whose amount is fixed and defined by the
inumParms argument. During the HVS performance, all these parameters are
variant and can be applied to any sound synthesis technique, as well as
to any global control for algorithmic composition and any other kind of
level. The user must previously define several sets of fixed values for
each HVS parameter, each set corresponding to a determinate synthesis
configuration. Each set of values is called snapshot, and can be
considered as the coordinates of a bound of a multi-dimensional space.
The HVS consists on moving a point in this multi-dimensional space (by
using a special motion pointer, see below), according and inside the
bounds defined by the snapshots. You can fix any amount of HVS
parameters (each parameter being a dimension of the multi-dimensional
space), even a huge number, the limit only depends on the processing
power (and the memory) of your computer and on the complexity of the
sound-synthesis you will use.

The HVS cube (or square or line). This is the matrix (of 3, 2 or 1
dimensions, according to the hvs opcode you intend to use) of
“mainstays” (or pivot) points of HVS. The total amount of pivot-points
depends on the value of the inumPointsX, inumPointsY and inumPointsZ
arguments. In the case of a 3-dimensional HVS matrix you can define, for
instance, 3 points for the X dimension, 5 for the Y dimension and 2 for
the Z dimension. In this case, the total number of pivot-points is 3 * 5
* 2 = 30. With this set of pivot points, the cube Is divided into
smaller cubed zones each one bounded by eight nearby points. Each point
is numbered. The numeral order of these points is enstabilished in the
following way: number zero is the first point, number 1 the second and
so on. Assuming you are using a 3-dimensional HVS cube having the number
of points above mentioned (i.e. 3, 5 and 2 respectively for the X, Y and
Z axis), the first point (point zero) is the upper-left-front vertex of
the cube, by facing the XY plane of the cube. The second point is the
middle point of the upper front edge of the cube and so on. You can
refer to the figure below in order to understand how the numeral order
of the pivot-points proceeds:

For the 2-dimensional HVS, it is the same, by only omitting the rear
cube face, so each zone is bounded by 4 pivot-points instead of 8. For
the 1-dimensional HVS, the whole thing is even simpler because it is a
line with the pivot-points proceeding from left to right. Each point is
coupled with a snapshot.

Snapshot order, as stored into the iSnapTab, can or cannot follow the
order of the pivot-points numbers. In fact it is possible to alter this
order by means the iPositionsTab, a table that remaps the position of
each snapshot in relation to the pivot points. The iPositionsTab is made
up of the positions of the snapshots (contained in the iSnapTab) in the
two-dimensional grid. Each subsequent element is actually a pointer
representing the position in the iSnapTab. For example, in a
2-dimensional HVS matrix such as the following (in this case having
inumPointsX = 3 and inumPointsY = 5:

Table 9. 

5       7       1
3       4       9
6       2       0
4       1       3
8       2       7

These numbers (to be stored in the iSnapTab table by using, for
instance, the GEN02 function generator) represents the snapshot position
within the grid (in this case a 3x5 matrix). So, the first element 5,
has index zero and represents the 6th (element zero is the first)
snapshot contained in the iSnapTab, the second element 7 represents the
8th element of iSnapTab and so on. Summing up, the vertices of each zone
(a cubed zone is delimited by 8 vertices; a squared zone by 4 vertices
and a linear zone by 2 points) are coupled with a determinate snapshot,
whose number is remapped by the iSnapTab.

Output values of the HVS are influenced by the motion pointer, a point
whose position, in the HVS cube (or square or segment) is determined by
the kx, ky and kz arguments. The values of these arguments, which must
be in the 0 to 1 range, are externally set by the user. The output
values, whose amount is equal to the inumParms argument, are stored in
the iOutTab, a table that must be already allocated by the user, and
must be at least inumParms size. In what way the motion pointer
influences the output? Well, when the motion pointer falls in a
determinate cubed zone, delimited, for instance, by 8 vertices (or pivot
points), we assume that each vertex has associated a different snapshot
(i.e. a set of inumParms values), well, the output will be the weighted
average value of the 8 vertices, calculated according on the distance of
the motion pointer from each of the 8 vertices. In the case of a default
behavior, when the iConfigTab argument is not set, the exact output is
calculated by using linear interpolation which is applied to each
different parameter of the HVS. Anyway, it is possible to influence this
behavior by setting the iConfigTab argument to a number of a table whose
contents can affect one or more HVS parameters. The iConfigTab table
elements are associated to each HVS parameter and their values affect
the HVS output in the following way:

  * If iConfigTab is equal to -1, corresponding output is skipped, i.e.
    the element is not calculated, leaving corresponding element value
    in the iOutTab unchanged;

  * If iConfigTab is equal to zero, then the normal HVS output is
    calculated (by using weighted average of the nearest vertex of
    current zone where it falls the motion pointer);

  * If iConfigTab element is equal to an integer number > zero, then the
    contents of a table having that number is used as a shape of a
    table-based interpolation.


===========================================================================
hvs2                                                                   *hvs2*

  Description

hvs2 allows two-dimensional Hyper Vectorial Synthesis (HVS) controlled
by externally-updated k-variables.

  Syntax

hvs2 kx, ky, inumParms, inumPointsX, inumPointsY, iOutTab, iPositionsTab, iSnapTab [, iConfigTab]

  Initialization

inumParms - number of parameters controlled by the HVS. Each HVS
snapshot is made up of inumParms elements.

inumPointsX, inumPointsY - number of points that each dimension of the
HVS cube (or square in case of two-dimensional HVS; or line in case of
one-dimensional HVS) is made up.

iOutTab - number of the table receiving the set of output-parameter
instant values of the HVS. The total amount of parameters is defined by
the inumParms argument.

iPositionsTab – a table filled with the individual positions of
snapshots in the HVS matrix (see below for more information).

iSnapTab – a table filled with all the snapshots. Each snapshot is made
up of a set of parameter values. The amount of elements contained in
each snapshots is specified by the inumParms argument. The set of
elements of each snapshot follows (and is adjacent) to the previous one
in this table. So the total size of this table should be >= to inumParms
multiplied the number of snapshots you intend to store for the HVS.

iConfigTab – (optional) a table containing the behavior of the HVS for
each parameter. If the value of iConfigTab is zero (default), this
argument is ignored, meaning that each parameter is treated with linear
interpolation by the HVS. If iConfigTab is different than zero, then it
must refer to an existing table whose contents are in its turn referring
to a particolar kind of interpolation. In this table, a value of -1
indicates that corresponding parameter is leaved unchanged (ignored) by
the HVS; a value of zero indicates that corresponding parameter is
treated with linear-interpolation; each other values must be integer
numbers indicating an existing table filled with a shape which will
determine the kind of special interpolation to be used (table-based
interpolation).

  Performance

kx, ky - these are externally-modified variables which controls the
motion of the pointer in the HVS matrix cube (or square or line in case
of HVS matrices made up of less than 3 dimensions). The range of these
input arguments must be 0 to 1.

Hyper Vectorial Synthesis is a technique that allows control of a huge
set of parameters by using a simple and global approach. The key
concepts of the HVS are:

The set of HVS parameters, whose amount is fixed and defined by the
inumParms argument. During the HVS performance, all these parameters are
variant and can be applied to any sound synthesis technique, as well as
to any global control for algorithmic composition and any other kind of
level. The user must previously define several sets of fixed values for
each HVS parameter, each set corresponding to a determinate synthesis
configuration. Each set of values is called snapshot, and can be
considered as the coordinates of a bound of a multi-dimensional space.
The HVS consists on moving a point in this multi-dimensional space (by
using a special motion pointer, see below), according and inside the
bounds defined by the snapshots. You can fix any amount of HVS
parameters (each parameter being a dimension of the multi-dimensional
space), even a huge number, the limit only depends on the processing
power (and the memory) of your computer and on the complexity of the
sound-synthesis you will use.

The HVS cube (or square or line). This is the matrix (of 3, 2 or 1
dimensions, according to the hvs opcode you intend to use) of
“mainstays” (or pivot) points of HVS. The total amount of pivot-points
depends on the value of the inumPointsX, inumPointsY and inumPointsZ
arguments. In the case of a 3-dimensional HVS matrix you can define, for
instance, 3 points for the X dimension, 5 for the Y dimension and 2 for
the Z dimension. In this case, the total number of pivot-points is 3 * 5
* 2 = 30. With this set of pivot points, the cube Is divided into
smaller cubed zones each one bounded by eight nearby points. Each point
is numbered. The numeral order of these points is enstabilished in the
following way: number zero is the first point, number 1 the second and
so on. Assuming you are using a 3-dimensional HVS cube having the number
of points above mentioned (i.e. 3, 5 and 2 respectively for the X, Y and
Z axis), the first point (point zero) is the upper-left-front vertex of
the cube, by facing the XY plane of the cube. The second point is the
middle point of the upper front edge of the cube and so on. You can
refer to the figure below in order to understand how the numeral order
of the pivot-points proceeds:

For the 2-dimensional HVS, it is the same, by only omitting the rear
cube face, so each zone is bounded by 4 pivot-points instead of 8. For
the 1-dimensional HVS, the whole thing is even simpler because it is a
line with the pivot-points proceeding from left to right. Each point is
coupled with a snapshot.

Snapshot order, as stored into the iSnapTab, can or cannot follow the
order of the pivot-points numbers. In fact it is possible to alter this
order by means the iPositionsTab, a table that remaps the position of
each snapshot in relation to the pivot points. The iPositionsTab is made
up of the positions of the snapshots (contained in the iSnapTab) in the
two-dimensional grid. Each subsequent element is actually a pointer
representing the position in the iSnapTab. For example, in a
2-dimensional HVS matrix such as the following (in this case having
inumPointsX = 3 and inumPointsY = 5:

Table 10. 

5       7       1
3       4       9
6       2       0
4       1       3
8       2       7

These numbers (to be stored in the iSnapTab table by using, for
instance, the GEN02 function generator) represents the snapshot position
within the grid (in this case a 3x5 matrix). So, the first element 5,
has index zero and represents the 6th (element zero is the first)
snapshot contained in the iSnapTab, the second element 7 represents the
8th element of iSnapTab and so on. Summing up, the vertices of each zone
(a cubed zone is delimited by 8 vertices; a squared zone by 4 vertices
and a linear zone by 2 points) are coupled with a determinate snapshot,
whose number is remapped by the iSnapTab.

Output values of the HVS are influenced by the motion pointer, a point
whose position, in the HVS cube (or square or segment) is determined by
the kx, ky and kz arguments. The values of these arguments, which must
be in the 0 to 1 range, are externally set by the user. The output
values, whose amount is equal to the inumParms argument, are stored in
the iOutTab, a table that must be already allocated by the user, and
must be at least inumParms size. In what way the motion pointer
influences the output? Well, when the motion pointer falls in a
determinate cubed zone, delimited, for instance, by 8 vertices (or pivot
points), we assume that each vertex has associated a different snapshot
(i.e. a set of inumParms values), well, the output will be the weighted
average value of the 8 vertices, calculated according on the distance of
the motion pointer from each of the 8 vertices. In the case of a default
behavior, when the iConfigTab argument is not set, the exact output is
calculated by using linear interpolation which is applied to each
different parameter of the HVS. Anyway, it is possible to influence this
behavior by setting the iConfigTab argument to a number of a table whose
contents can affect one or more HVS parameters. The iConfigTab table
elements are associated to each HVS parameter and their values affect
the HVS output in the following way:

  * If iConfigTab is equal to -1, corresponding output is skipped, i.e.
    the element is not calculated, leaving corresponding element value
    in the iOutTab unchanged;

  * If iConfigTab is equal to zero, then the normal HVS output is
    calculated (by using weighted average of the nearest vertex of
    current zone where it falls the motion pointer);

  * If iConfigTab element is equal to an integer number > zero, then the
    contents of a table having that number is used as a shape of a
    table-based interpolation.


===========================================================================
hvs3                                                                   *hvs3*

  Description

hvs3 allows three-dimensional Hyper Vectorial Synthesis (HVS) controlled
by externally-updated k-variables.

  Syntax

hvs3 kx, ky, kz, inumParms, inumPointsX, inumPointsY, inumPointsZ, iOutTab, iPositionsTab, iSnapTab [, iConfigTab]

  Initialization

inumParms - number of parameters controlled by the HVS. Each HVS
snapshot is made up of inumParms elements.

inumPointsX, inumPointsY, inumPointsZ - number of points that each
dimension of the HVS cube (or square in case of two-dimensional HVS; or
line in case of one-dimensional HVS) is made up.

iOutTab - number of the table receiving the set of output-parameter
instant values of the HVS. The total amount of parameters is defined by
the inumParms argument.

iPositionsTab – a table filled with the individual positions of
snapshots in the HVS matrix (see below for more information).

iSnapTab – a table filled with all the snapshots. Each snapshot is made
up of a set of parameter values. The amount of elements contained in
each snapshots is specified by the inumParms argument. The set of
elements of each snapshot follows (and is adjacent) to the previous one
in this table. So the total size of this table should be >= to inumParms
multiplied the number of snapshots you intend to store for the HVS.

iConfigTab – (optional) a table containing the behavior of the HVS for
each parameter. If the value of iConfigTab is zero (default), this
argument is ignored, meaning that each parameter is treated with linear
interpolation by the HVS. If iConfigTab is different than zero, then it
must refer to an existing table whose contents are in its turn referring
to a particolar kind of interpolation. In this table, a value of -1
indicates that corresponding parameter is leaved unchanged (ignored) by
the HVS; a value of zero indicates that corresponding parameter is
treated with linear-interpolation; each other values must be integer
numbers indicating an existing table filled with a shape which will
determine the kind of special interpolation to be used (table-based
interpolation).

  Performance

kx, ky, kz - these are externally-modified variables which controls the
motion of the pointer in the HVS matrix cube (or square or line in case
of HVS matrices made up of less than 3 dimensions). The range of these
input arguments must be 0 to 1.

Hyper Vectorial Synthesis is a technique that allows control of a huge
set of parameters by using a simple and global approach. The key
concepts of the HVS are:

The set of HVS parameters, whose amount is fixed and defined by the
inumParms argument. During the HVS performance, all these parameters are
variant and can be applied to any sound synthesis technique, as well as
to any global control for algorithmic composition and any other kind of
level. The user must previously define several sets of fixed values for
each HVS parameter, each set corresponding to a determinate synthesis
configuration. Each set of values is called snapshot, and can be
considered as the coordinates of a bound of a multi-dimensional space.
The HVS consists on moving a point in this multi-dimensional space (by
using a special motion pointer, see below), according and inside the
bounds defined by the snapshots. You can fix any amount of HVS
parameters (each parameter being a dimension of the multi-dimensional
space), even a huge number, the limit only depends on the processing
power (and the memory) of your computer and on the complexity of the
sound-synthesis you will use.

The HVS cube (or square or line). This is the matrix (of 3, 2 or 1
dimensions, according to the hvs opcode you intend to use) of
“mainstays” (or pivot) points of HVS. The total amount of pivot-points
depends on the value of the inumPointsX, inumPointsY and inumPointsZ
arguments. In the case of a 3-dimensional HVS matrix you can define, for
instance, 3 points for the X dimension, 5 for the Y dimension and 2 for
the Z dimension. In this case, the total number of pivot-points is 3 * 5
* 2 = 30. With this set of pivot points, the cube Is divided into
smaller cubed zones each one bounded by eight nearby points. Each point
is numbered. The numeral order of these points is enstabilished in the
following way: number zero is the first point, number 1 the second and
so on. Assuming you are using a 3-dimensional HVS cube having the number
of points above mentioned (i.e. 3, 5 and 2 respectively for the X, Y and
Z axis), the first point (point zero) is the upper-left-front vertex of
the cube, by facing the XY plane of the cube. The second point is the
middle point of the upper front edge of the cube and so on. You can
refer to the figure below in order to understand how the numeral order
of the pivot-points proceeds:

For the 2-dimensional HVS, it is the same, by only omitting the rear
cube face, so each zone is bounded by 4 pivot-points instead of 8. For
the 1-dimensional HVS, the whole thing is even simpler because it is a
line with the pivot-points proceeding from left to right. Each point is
coupled with a snapshot.

Snapshot order, as stored into the iSnapTab, can or cannot follow the
order of the pivot-points numbers. In fact it is possible to alter this
order by means the iPositionsTab, a table that remaps the position of
each snapshot in relation to the pivot points. The iPositionsTab is made
up of the positions of the snapshots (contained in the iSnapTab) in the
two-dimensional grid. Each subsequent element is actually a pointer
representing the position in the iSnapTab. For example, in a
2-dimensional HVS matrix such as the following (in this case having
inumPointsX = 3 and inumPointsY = 5:

Table 11. 

5       7       1
3       4       9
6       2       0
4       1       3
8       2       7

These numbers (to be stored in the iSnapTab table by using, for
instance, the GEN02 function generator) represents the snapshot position
within the grid (in this case a 3x5 matrix). So, the first element 5,
has index zero and represents the 6th (element zero is the first)
snapshot contained in the iSnapTab, the second element 7 represents the
8th element of iSnapTab and so on. Summing up, the vertices of each zone
(a cubed zone is delimited by 8 vertices; a squared zone by 4 vertices
and a linear zone by 2 points) are coupled with a determinate snapshot,
whose number is remapped by the iSnapTab.

Output values of the HVS are influenced by the motion pointer, a point
whose position, in the HVS cube (or square or segment) is determined by
the kx, ky and kz arguments. The values of these arguments, which must
be in the 0 to 1 range, are externally set by the user. The output
values, whose amount is equal to the inumParms argument, are stored in
the iOutTab, a table that must be already allocated by the user, and
must be at least inumParms size. In what way the motion pointer
influences the output? Well, when the motion pointer falls in a
determinate cubed zone, delimited, for instance, by 8 vertices (or pivot
points), we assume that each vertex has associated a different snapshot
(i.e. a set of inumParms values), well, the output will be the weighted
average value of the 8 vertices, calculated according on the distance of
the motion pointer from each of the 8 vertices. In the case of a default
behavior, when the iConfigTab argument is not set, the exact output is
calculated by using linear interpolation which is applied to each
different parameter of the HVS. Anyway, it is possible to influence this
behavior by setting the iConfigTab argument to a number of a table whose
contents can affect one or more HVS parameters. The iConfigTab table
elements are associated to each HVS parameter and their values affect
the HVS output in the following way:

  * If iConfigTab is equal to -1, corresponding output is skipped, i.e.
    the element is not calculated, leaving corresponding element value
    in the iOutTab unchanged;

  * If iConfigTab is equal to zero, then the normal HVS output is
    calculated (by using weighted average of the nearest vertex of
    current zone where it falls the motion pointer);

  * If iConfigTab element is equal to an integer number > zero, then the
    contents of a table having that number is used as a shape of a
    table-based interpolation.


===========================================================================
i                                                                         *i*

  Description

Returns an init-type equivalent of a k-rate argument, or directly
returns an i-rate argument.

  Syntax

i(x) (control-rate or init-rate arg)

Value converters perform arithmetic translation from units of one kind
to units of another. The result can then be a term in a further expression.

  Note

Using i() with a k-rate expression argument is not recommended, and can
produce unexpected results.


===========================================================================
if                                                                       *if*

  Description

if...igoto -- conditional branch at initialization time, depending on
the truth value of the logical expression ia R ib. The branch is taken
only if the result is true.

if...kgoto -- conditional branch during performance time, depending on
the truth value of the logical expression ka R kb. The branch is taken
only if the result is true.

if...goto -- combination of the above. Condition tested on every pass.

if...then -- allows the ability to specify conditional if/else/endif
blocks. All if...then blocks must end with an endif statement. elseif
and else statements are optional. Any number of elseif statements are
allowed. Only one else statement may occur and it must be the last
conditional statement before the endif statement. Nested if...then
blocks are allowed.

  Note

Note that if the condition uses a k-rate variable (for instance, “if
kval > 0”), the if...goto or if...then statement will be ignored during
the i-time pass. This allows for opcode initialization, even if the
k-rate variable has already been assigned an appropriate value by an
earlier init statement.

  Syntax

if ia R ib igoto label

if ka R kb kgoto label

if xa R xb goto label

if xa R xb then

where label is in the same instrument block and is not an expression,
and where R is one of the Relational operators (<, =, <=, ==, !=) (and =
for convenience, see also under Conditional Values).

If goto or then is used instead of kgoto or igoto, the behavior is
determined by the type being compared. If the comparison used k-type
variables, kgoto is used and viceversa.

  Note

If/then/goto statements cannot do audio-type comparisons. You can't put
a-type variables in the comparison expressions for these opcodes. The
reason for this is that audio variables are actually vectors, which
can't be compared in the same way as scalars. If you need to compare
individua audio samples, use kr = 1 or Comparators


===========================================================================
fftinv                                                               *fftinv*

  Description

Applies an Inverse Fast Fourier Transform to a complex-value input
1-dimensional array producing a complex-valued output. The output is
another array containing the complex-valued signal, and both arrays are
arranged in interleaved real-imaginary format. The output array will
have the same size as the input, and the transform size will be
equivalent to half of the length of the array. Non-power-of-two
transforms are limited to even sizes with not too many factors.

  Syntax

kout[] fftinv kin[]

  Performance

kout[] -- output array containing the complex-valued output. It will be
created if it does not exist.

kin[] -- input array containing the complex-valued input.


===========================================================================
igoto                                                                 *igoto*

  Description

During the i-time pass only, unconditionally transfer control to the
statement labeled by label.

  Syntax

igoto label

where label is in the same instrument block and is not an expression.


===========================================================================
ihold                                                                 *ihold*

  Description

Causes a finite-duration note to become a “held” note

  Syntax

ihold

  Performance

ihold -- this i-time statement causes a finite-duration note to become a
“held” note. It thus has the same effect as a negative p3 ( see score i
Statement), except that p3 here remains positive and the instrument
reclassifies itself to being held indefinitely. The note can be turned
off explicitly with turnoff, or its space taken over by another note of
the same instrument number (i.e. it is tied into that note). Effective
at i-time only; no-op during a reinit pass.


===========================================================================
imagecreate                                                     *imagecreate*

  Description

Create an empty image of a given size. Individual pixel values can then
be set with. imagegetpixel.

  Syntax

iimagenum imagecreate iwidth, iheight

  Initialization

iimagenum -- number assigned to the created image.

iwidth -- desired image width.

iheight -- desired image height.


===========================================================================
imagefree                                                         *imagefree*

  Description

Frees memory allocated for a previously loaded or created image.

  Syntax

imagefree iimagenum

  Initialization

iimagenum -- reference of the image to free.


===========================================================================
imagegetpixel                                                 *imagegetpixel*

  Description

Return the RGB pixel values of a previously opened or created image. An
image can be loaded with imageload. An empty image can be created with
imagecreate.

  Syntax

ared, agreen, ablue imagegetpixel iimagenum, ax, ay

kred, kgreen, kblue imagegetpixel iimagenum, kx, ky

  Initialization

iimagenum -- the reference of the image.. It should be a value returned
by imageload or imagecreate.

  Performance

ax (kx) -- horizontal pixel position (must be a float from 0 to 1).

ay (ky) -- vertical pixel position (must be a float from 0 to 1).

ared (kred) -- red value of the pixel (mapped to a float from 0 to 1).

agreen (kgreen) -- green value of the pixel (mapped to a float from 0 to
1).

ablue (kblue) -- blue value of the pixel (mapped to a float from 0 to 1).


===========================================================================
imageload                                                         *imageload*

  Description

Load an image and return a reference to it. Individual pixel values can
then be accessed with imagegetpixel.

  Note

The image processing opcodes can only load png images

  Syntax

iimagenum imageload filename

  Initialization

iimagenum -- number assigned to the loaded image.

filename -- The filename of the image to load (should be a valid PNG
image file).


===========================================================================
imagesave                                                         *imagesave*

  Description

Save a previously created image. An empty image can be created with
imagecreate and its pixel RGB values can be set with imagesetpixel. The
image will be saved in PNG format.

  Syntax

imagesave iimagenum, filename

  Initialization

iimagenum -- the reference of the image to be save. It should be a value
returned by imagecreate.

filename -- The filename to use to save the image.


===========================================================================
imagesetpixel                                                 *imagesetpixel*

  Description

Set the RGB value of a pixel inside a previously opened or created
image. An image can be loaded with imageload. An empty image can be
created with imagecreate and saved with imagesave.

  Syntax

imagesetpixel iimagenum, ax, ay, ared, agreen, ablue

imagesetpixel iimagenum, kx, ky, kred, kgreen, kblue

  Initialization

iimagenum -- the reference of the image.. It should be a value returned
by imageload or imagecreate.

  Performance

ax (kx) -- horizontal pixel position (must be a float from 0 to 1).

ay (ky) -- vertical pixel position (must be a float from 0 to 1).

ared (kred) -- red value of the pixel (mapped to a float from 0 to 1).

agreen (kgreen) -- green value of the pixel (mapped to a float from 0 to
1).

ablue (kblue) -- blue value of the pixel (mapped to a float from 0 to 1).


===========================================================================
imagesize                                                         *imagesize*

  Description

Return the width and height of a previously opened or created image. An
image can be loaded with imageload. An empty image can be created with
imagecreate.

  Syntax

iwidth, iheight imagesize iimagenum

  Initialization

iimagenum -- the reference of the image.. It should be a value returned
by imageload or imagecreate.

iwidth -- image width.

iheight -- image height.


===========================================================================
in                                                                       *in*

  Description

Reads audio data from an external device or stream.

  Warning

There are two versions of this opcode. The first is designed to be used
only with orchestras that have inchnls=1. Doing so with orchestras with
inchnls > 1 will cause incorrect audio input.

The second form will read multiple channels into an array.

  Syntax

ar1 in

aarray in

  Performance

Form 1 reads mono audio data from an external device or stream. If the
command-line -i flag is set, sound is read continuously from the audio
input stream (e.g. stdin or a soundfile) into an internal buffer. Any
number of these opcodes can read freely from this buffer.

The second format will read upto ichnls of audio into an audio array,
which must be initialised.


===========================================================================
in32                                                                   *in32*

  Description

Reads a 32-channel audio signal from an external device or stream.

  Warning

This opcode is designed to be used only with orchestras that have
nchnls_i=32. Doing so with orchestras with nchnls_i > 32 will cause
incorrect audio input.

  Syntax

ar1, ar2, ar3, ar4, ar5, ar6, ar7, ar8, ar9, ar10, ar11, ar12, ar13, ar14, \
      ar15, ar16, ar17, ar18, ar19, ar20, ar21, ar22, ar23, ar24, ar25, ar26, \
      ar27, ar28, ar29, ar30, ar31, ar32 in32

  Performance

in32 reads a 32-channel audio signal from an external device or stream.
If the command-line -i flag is set, sound is read continuously from the
audio input stream (e.g. stdin or a soundfile) into an internal buffer.


===========================================================================
inch                                                                   *inch*

  Description

Reads from numbered channels in an external audio signal or stream.

  Syntax

ain1[, ...] inch kchan1[,...]

  Performance

ain1, ... - input audio signals

kchan1,... - channel numbers

inch reads from numbered channels determined by the corresponding kchan
into the associated ain. If the command-line -i flag is set, sound is
read continuously from the audio input stream (e.g. stdin or a
soundfile). inch can also be used to receive audio in realtime from the
audio interface using -iadc.

  Note

The highest number for kchan available for use with inch depends on
nchnls_i. If kchan is greater than nchnls_i, ain will be silent. Note
that inch will give a warning but not an error in this case.


===========================================================================
inh                                                                     *inh*

  Description

Reads six-channel audio data from an external device or stream.

  Warning

This opcode is designed to be used only with orchestras that have
nchnls_i=6. Doing so with orchestras with nchnls_i > 6 will cause
incorrect audio input.

  Syntax

ar1, ar2, ar3, ar4, ar5, ar6 inh

  Performance

Reads six-channel audio data from an external device or stream. If the
command-line -i flag is set, sound is read continuously from the audio
input stream (e.g. stdin or a soundfile) into an internal buffer. Any
number of these opcodes can read freely from this buffer.


===========================================================================
init                                                                   *init*

  Syntax

ares init iarg

ires init iarg

kres init iarg

ares, ...  init iarg, ...

ires, ... init iarg, ...

kres, ... init iarg, ...

tab init isize[, ival]

  Description

Put the value of the i-time expression into a k- or a-rate variable.

  Initialization

Puts the value of the i-time expression iarg into a k-, a-rate or t-
variable, i.e., initialize the result. Note that init provides the only
case of an init-time statement being permitted to write into a perf-time
(k- or a-rate) result cell; the statement has no effect at perf-time.

Since version 5.13 it is possible to initialise upto 24 variables of the
same class in one statement. If there are more output variables than
input expressions then the last one is repeated. It is an error to have
more inputs than outputs.

The t-variable form was introduced in 5.14 and allocated space for a
vector or the given size, initialised to the given value (default value
is zero).


===========================================================================
initc14                                                             *initc14*

  Description

Initializes the controllers used to create a 14-bit MIDI value.

  Syntax

initc14 ichan, ictlno1, ictlno2, ivalue

  Initialization

ichan -- MIDI channel (1-16)

ictlno1 -- most significant byte controller number (0-127)

ictlno2 -- least significant byte controller number (0-127)

ivalue -- floating point value (must be within 0 to 1)

  Performance

initc14 can be used together with both midic14 and ctrl14 opcodes for
initializing the first controller's value. ivalue argument must be set
with a number within 0 to 1. An error occurs if it is not. Use the
following formula to set ivalue according with midic14 and ctrl14 min
and max range:

ivalue = (initial_value - min) / (max - min)


===========================================================================
initc21                                                             *initc21*

  Description

Initializes the controllers used to create a 21-bit MIDI value.

  Syntax

initc21 ichan, ictlno1, ictlno2, ictlno3, ivalue

  Initialization

ichan -- MIDI channel (1-16)

ictlno1 -- most significant byte controller number (0-127)

ictlno2 -- medium significant byte controller number (0-127)

ictlno3 -- least significant byte controller number (0-127)

ivalue -- floating point value (must be within 0 to 1)

  Performance

initc21 can be used together with both midic21 and ctrl21 opcodes for
initializing the first controller's value. ivalue argument must be set
with a number within 0 to 1. An error occurs if it is not. Use the
following formula to set ivalue according with midic21 and ctrl21 min
and max range:

ivalue = (initial_value - min) / (max - min)


===========================================================================
initc7                                                               *initc7*

  Description

Initializes MIDI controller ictlno with ivalue

  Syntax

initc7 ichan, ictlno, ivalue

  Initialization

ichan -- MIDI channel (1-16)

ictlno -- controller number (0-127)

ivalue -- floating point value (must be within 0 to 1)

  Performance

initc7 can be used together with both midic7 and ctrl7 opcodes for
initializing the first controller's value. ivalue argument must be set
with a number within 0 to 1. An error occurs if it is not. Use the
following formula to set ivalue according with midic7 and ctrl7 min and
max range:

ivalue = (initial_value - min) / (max - min)


===========================================================================
inleta                                                               *inleta*

  Description

Receives an arate signal into an instrument through a named port.

  Syntax

asignal inleta Sname

  Initialization

Sname -- String name of the inlet port. The name of the inlet is
implicitly qualified by the instrument name or number, so it is valid to
use the same inlet name in more than one instrument (but not to use the
same inlet name twice in one instrument).

  Performance

asignal -- audio input signal

During performance, the arate inlet signal is received from each
instance of an instrument containing an outlet port to which this inlet
has been connected using the connect opcode. The signals of all the
outlets connected to an inlet are summed in the inlet.


===========================================================================
inletk                                                               *inletk*

  Description

Receives a krate signal into an instrument from a named port.

  Syntax

ksignal inletk Sname

  Initialization

Sname -- String name of the inlet port. The name of the inlet is
implicitly qualified by the instrument name or number, so it is valid to
use the same inlet name in more than one instrument (but not to use the
same inlet name twice in one instrument).

  Performance

ksignal -- krate input signal

During performance, the krate inlet signal is received from each
instance of an instrument containing an outlet port to which this inlet
has been connected using the connect opcode. The signals of all the
outlets connected to an inlet are summed in the inlet.


===========================================================================
inletkid                                                           *inletkid*

  Description

Receives a krate signal into an instrument from a named port.

  Syntax

ksignal inletkid Sname, SinstanceID

  Initialization

Sname -- String name of the inlet port. The name of the inlet is
implicitly qualified by the instrument name or number, so it is valid to
use the same inlet name in more than one instrument (but not to use the
same inlet name twice in one instrument).

SinstanceID -- String name of the outlet port's instance ID. This
enables the inlet to discriminate between different instances of the
outlet, e,g. one instance of the outlet might be created by a note
specifying one instance ID, and another instance might be created by a
note specifying another ID. This might be used, e.g., to situate
difference instances of an instrument at different points in an
Ambisonic space in a spatializing effects processor.

  Performance

ksignal -- krate input signal

During performance, the krate inlet signal is received from each
instance of an instrument containing an outlet port to which this inlet
has been connected using the connect opcode. The signals of all the
outlets that are connected to an inlet, but only those share the
specified instance ID, are summed in the inlet.


===========================================================================
inletf                                                               *inletf*

  Description

Receives an frate signal (fsig) into an instrument from a named port.

  Syntax

fsignal inletf Sname

  Initialization

Sname -- String name of the inlet port. The name of the inlet is
implicitly qualified by the instrument name or number, so it is valid to
use the same inlet name in more than one instrument (but not to use the
same inlet name twice in one instrument).

  Performance

ksignal -- frate input signal

During performance, the frate inlet signal is received from each
instance of an instrument containing an outlet port to which this inlet
has been connected using the connect opcode. The signals of all the
outlets connected to an inlet are combined in the inlet.


===========================================================================
inletv                                                               *inletv*

  Description

Receives an arate array signal into an instrument through a named port.

  Syntax

array inletv Sname

  Initialization

Sname -- String name of the inlet port. The name of the inlet is
implicitly qualified by the instrument name or number, so it is valid to
use the same inlet name in more than one instrument (but not to use the
same inlet name twice in one instrument).

  Performance

array -- audio rate array inlet signal

During performance, the arate array inlet signal is received from each
instance of an instrument containing an outlet port to which this inlet
has been connected using the connect opcode. The signals of all the
outlets connected to an inlet are summed in the inlet. The ports may
have any number of channels, but the inlet port must have the same
number of channels as the connected outlet ports.


===========================================================================
ino                                                                     *ino*

  Description

Reads eight-channel audio data from an external device or stream.

  Warning

This opcode is designed to be used only with orchestras that have
nchnls_i=8. Doing so with orchestras with nchnls_i > 8 will cause
incorrect audio input.

  Syntax

ar1, ar2, ar3, ar4, ar5, ar6, ar7, ar8 ino

  Performance

Reads eight-channel audio data from an external device or stream. If the
command-line -i flag is set, sound is read continuously from the audio
input stream (e.g. stdin or a soundfile) into an internal buffer. Any
number of these opcodes can read freely from this buffer.


===========================================================================
inq                                                                     *inq*

  Description

Reads quad audio data from an external device or stream.

  Warning

This opcode is designed to be used only with orchestras that have
nchnls_i=4. Doing so with orchestras with nchnls_i > 4 will cause
incorrect audio input.

  Syntax

ar1, ar2,  ar3, a4 inq

  Performance

Reads quad audio data from an external device or stream. If the
command-line -i flag is set, sound is read continuously from the audio
input stream (e.g. stdin or a soundfile) into an internal buffer. Any
number of these opcodes can read freely from this buffer.


===========================================================================
inrg                                                                   *inrg*

  Description

inrg reads audio from a range of adjacent audio channels from the audio
input device.

  Syntax

inrg kstart, ain1 [,ain2, ain3, ..., ainN]

  Performance

kstart - the number of the first channel of the input device to be
accessed (channel numbers starts with 1, which is the first channel)

ain1, ain2, ... ainN - the output arguments filled with the incoming
audio coming from corresponding channels.

inrg allows input from a range of adjacent channels from the input
device. kstart indicates the first channel to be accessed (channel 1 is
the first channel). The user must be sure that the number obtained by
summing kstart plus the number of accessed channels -1 is <= nchnls_i.

  Note

Note that this opcode is exceptional in that it produces its “output” on
the parameters to the right.


===========================================================================
ins                                                                     *ins*

  Description

Reads stereo audio data from an external device or stream.

  Warning

This opcode is designed to be used only with orchestras that have
nchnls_i=2. Doing so with orchestras with nchnls_i > 2 will cause
incorrect audio input.

  Syntax

ar1, ar2 ins

  Performance

Reads stereo audio data from an external device or stream. If the
command-line -i flag is set, sound is read continuously from the audio
input stream (e.g. stdin or a soundfile) into an internal buffer. Any
number of these opcodes can read freely from this buffer.


===========================================================================
insremot                                                           *insremot*

  Description

With the insremot and insglobal opcodes you are able to perform
instruments on remote machines and control them from a master machine.
The remote opcodes are implemented using the master/client model. All
the machines involved contain the same orchestra but only the master
machine contains the information of the score. During the performance
the master machine sends the note events to the clients. The insremot
opcode will send events from a source machine to one destination if you
want to send events to many destinations (broadcast) use the insglobal
opcode instead. These two opcodes can be used in combination.

  Syntax

insremot idestination, isource, instrnum [,instrnum...] 

  Initialization

idestination -- a string that is the intended client computer (e.g.
192.168.0.100). This is the destination host which receives the events
from the given instrument.

isource -- a string that is the intended server computer (e.g.
192.168.0.100). This is the source host which generates the events of
the given instrument and sends it to the address given by idestination.

instrnum -- a list of instrument numbers which will be played on the
destination machine

  Performance

  Note
If is essential the computers using this opcode have the same
byte-order, data size (double or float) and pointer size. One cannot use
it with mixed 32 and 64 computers for instance.

  Note
Internally this opcode may make use of the gethostname and gethostbyname
functions to determine the client's and server's IP address for checking
which messages are for which machine, or on non-windows system other
techniques. If a computer has more than one IP address there is no way
to control which IP address is found (but see below). On non-windows
systems the default network is eth0 or en0, and if that fails wlan0.
(Since version 6.05) the network to be used can be set with an
environment variable CS_ETHER.

  Note
The remote operation does not allow the sending of strings at all.


===========================================================================
insglobal                                                         *insglobal*

  Description

With the insremot and insglobal opcodes you are able to perform
instruments on remote machines and control them from a master machine.
The remote opcodes are implemented using the master/client model. All
the machines involved contain the same orchestra but only the master
machine contains the information of the score. During the performance
the master machine sends the note events to the clients. The insglobal
opcode sends the events to all the machines involved in the remote
concert. These machines are determined by the insremot definitions made
above the insglobal command. To send events to only one machine use
insremot.

  Syntax

insglobal isource, instrnum [,instrnum...] 

  Initialization

isource -- a string that is the intended server computer (e.g.
192.168.0.100). This is the source host which generates the events of
the given instrument(s) and sends it to all the machines involved in the
remote concert.

instrnum -- a list of instrument numbers which will be played on the
destination machines

  Performance

  Note
If is essential the computers using this opcode have the same
byte-order, data size (double or float) and pointer size. One cannot use
it with mixed 32 and 64 computers for instance.

  Note
Internally this opcode makes use of the gethostname and gethostbyname
functions to determine the client's and server's IP address for checking
which messages are for which machine. If a computer has more than one IP
address there is no way to control which IP address is found.

  Note
The remote operation does not allow the sending of strings at all.


===========================================================================
instr                                                                 *instr*

  Description

Starts an instrument block.

  Syntax

instr i, j, ...

  Initialization

Starts an instrument block defining instruments i, j, ...

i, j, ... must be numbers, not expressions. Any positive integer is
legal, and in any order, but excessively high numbers are best avoided.

  Note

There may be any number of instrument blocks in an orchestra.

Instruments can be defined in any order (but they will always be both
initialized and performed in ascending instrument number order, with the
exception of notes triggered by real time events that are initialized in
the order of being received but still performed in ascending instrument
number order). Instrument blocks cannot be nested (i.e. one block cannot
contain another).


===========================================================================
int                                                                     *int*

  Description

Returns the integer part of x.

  Syntax

int(x)  (init-rate or control-rate; also works at audio rate in Csound5)

where the argument within the parentheses may be an expression. Value
converters perform arithmetic translation from units of one kind to
units of another. The result can then be a term in a further expression.


===========================================================================
integ                                                                 *integ*

  Description

Modify a signal by integration.

  Syntax

ares integ asig [, iskip]

kres integ ksig [, iskip]

  Initialization

iskip (optional) -- initial disposition of internal save space (see
reson). The default value is 0.

  Performance

integ and diff perform integration and differentiation on an input
control signal or audio signal. Each is the converse of the other, and
applying both will reconstruct the original signal. Since these units
are special cases of low-pass and high-pass filters, they produce a
scaled (and phase shifted) output that is frequency-dependent. Thus diff
of a sine produces a cosine, with amplitude 2 * pi * Hz / sr that of the
original (for each component partial); integ will inversely affect the
magnitudes of its component inputs. With this understanding, these units
can provide useful signal modification.


===========================================================================
interp                                                               *interp*

  Description

Converts a control signal to an audio signal using linear interpolation.

  Syntax

ares interp ksig [, iskip] [, imode]
    [, ivalue]

  Initialization

iskip (optional, default=0) -- if non zero skips initialisation of
internal save space (see reson).

imode (optional, default=0) -- sets the initial output value to the
first k-rate input instead of zero. The following graphs show the output
of interp with a constant input value, in the original, when skipping
init, and in the new mode:

Example 422. iskip=0, imode=0

 |    ________
 |   /        
 |  /         
 | /          
 |/           
-+------------
 |            

Example 423. iskip=1, imode=0

(prev)
 |  __________
 | /          
 |/           
 |            
 |            
-+------------
 |            

Example 424. iskip=0, imode=1

 |____________
 |
 |
 |
 |
-+------------
 |

ivalue (optional, default=0) -- initial value if both imode and iskip
are zero.

  Performance

ksig -- input k-rate signal.

interp converts a control signal to an audio signal. It uses linear
interpolation between successive kvals.


===========================================================================
invalue                                                             *invalue*

  Description

Reads a k-rate or i-rate signal or string from a user-defined channel.

  Syntax

ivalue invalue "channel name"

kvalue invalue "channel name"

Sname invalue "channel name"

  Performance

ivalue, kvalue -- The value that is read from the channel.

Sname -- The string variable that is read from the channel.

"channel name" -- An integer, string (in double-quotes), or string
variable identifying the channel.


===========================================================================
inx                                                                     *inx*

  Description

Reads a 16-channel audio signal from an external device or stream.

  Warning

This opcode is designed to be used only with orchestras that have
nchnls=16. Doing so with orchestras with nchnls > 16 will cause
incorrect audio input.

  Syntax

ar1, ar2, ar3, ar4, ar5, ar6, ar7, ar8, ar9, ar10, ar11, ar12, \
      ar13, ar14, ar15, ar16 inx

  Performance

inx reads a 16-channel audio signal from an external device or stream.
If the command-line -i flag is set, sound is read continuously from the
audio input stream (e.g. stdin or a soundfile) into an internal buffer.


===========================================================================
inz                                                                     *inz*

  Description

Reads multi-channel audio samples into a ZAK array from an external
device or stream.

  Syntax

inz ksig1

  Performance

inz reads audio samples in nchnls into a ZAK array starting at ksig1. If
the command-line -i flag is set, sound is read continuously from the
audio input stream (e.g. stdin or a soundfile) into an internal buffer.


===========================================================================
JackoAudioIn                                                   *JackoAudioIn*

  Description

Receives an audio signal from a Jack audio input port inside this
instance of Csound, which in turn has received the signal from its
connected external Jack audio output port.

  Syntax

asignal JackoAudioIn ScsoundPortName

  Initialization

ScsoundPortName -- The short name ("portname") of the internal Jack
audio input port.

  Performance

asignal -- Audio received from the external Jack output port to which
ScsoundPortName is connected.


===========================================================================
JackoAudioInConnect                                     *JackoAudioInConnect*

  Description

In the orchestra header, creates an audio connection from an external
Jack audio output port to a Jack audio input port inside this instance
of Csound.

  Syntax

JackoAudioInConnect SexternalPortName, ScsoundPortName

  Initialization

SexternalPortName -- The full name ("clientname:portname") of an
external Jack audio output port.

ScsoundPortName -- The short name ("portname") of the internal Jack
audio input port.

  Performance

The actual audio must be read with the JackoAudioIn opcode.


===========================================================================
JackoAudioOut                                                 *JackoAudioOut*

  Description

Sends an audio signal to an internal Jack audio output port, and in turn
to its connected external Jack audio input port.

Note that it is possible to send audio out via Jack to the system audio
interface, while at the same time rendering to a regular Csound output
soundfile.

  Syntax

JackoAudioOut  ScsoundPortName, asignal

  Initialization

ScsoundPortName -- The short name ("portname") of the internal Jack
audio output port.

  Performance

asignal -- Audio to be sent to the external Jack audio input port to
which CsoundPortName is connected.

Audio from multiple instances of the opcode sending to the same Jack
port is summed before sending.


===========================================================================
JackoAudioOutConnect                                   *JackoAudioOutConnect*

  Description

In the orchestra header, creates an audio connection from a Jack audio
output port inside this instance of Csound to an external Jack audio
input port.

  Syntax

JackoAudioOutConnect ScsoundPortName, SexternalPortName

  Initialization

ScsoundPortName -- The short name ("portname") of the internal Jack
audio output port.

SexternalPortName -- The full name ("clientname:portname") of an
external Jack audio input port.

  Performance

The actual audio must be written with the JackoAudioOut opcode.


===========================================================================
JackoFreewheel                                               *JackoFreewheel*

  Description

Turns Jack's freewheeling mode on or off.

When freewheeling is on, if supported by the rest of the Jack system,
Csound will run as fast as possible, which may be either faster or
slower than real time.

This is essential for rendering scores that are too dense for real-time
performance to a soundfile, without xruns or dropouts.

  Syntax

JackoFreewheel [ienabled]

  Initialization

ienabled -- Turns freewheeling on (the default) or off.


===========================================================================
JackoInfo                                                         *JackoInfo*

  Description

Prints the Jack daemon and client names, the sampling rate and frames
per period, and all active Jack port names, types, states, and connections.

  Syntax

JackoInfo 

  Initialization

May be called any number of times in the orchestra header, for example
both before and after creating Jack ports in the Csound orchestra header.


===========================================================================
JackoInit                                                         *JackoInit*

  Description

Initializes this instance of Csound as a Jack client.

Csound's sr must be equal to the Jack daemon's frames per second.

Csound's ksmps must be equal to the Jack daemon's frames per period.

Frames per period must not only (a) be a power of 2, but also (b) go
evenly into the frames per second, e.g. 128 frames per period goes into
48000 frames per second 375 times, for a latency or MIDI time
granularity of about 2.7 milliseconds (as good as or better than the
absolute best human performers).

The order of processing of all signals that pass from Jack input ports,
through Csound processing, and to Jack output ports, must be properly
determined by sequence of instrument and opcode definition within Csound.

  Syntax

JackoInit ServerName, SclientName

  Initialization

SclientName -- The name of the Jack client; normally, should be "csound".

ServerName -- The name of the Jack daemon; normally, will be "default".

This opcode must be called once and only once in the orchestra header,
and before any other Jack opcodes. If more than one instance of Csound
is using the Jack opcodes at the same time, then each instance of Csound
must use a different client name.


===========================================================================
JackoMidiInConnect                                       *JackoMidiInConnect*

  Description

In the orchestra header, creates a MIDI connection from an external Jack
MIDI output port to this instance of Csound.

  Syntax

JackoMidiInConnect SexternalPortName, ScsoundPortName

  Initialization

SexternalPortName -- The full name ("clientname:portname") of an
external Jack MIDI output port.

ScsoundPortName -- The short name ("portname") of the internal Jack MIDI
input port.

Must be used in conjunction with the -M0 -+rtmidi=null Csound
command-line options. Can be used in with the MIDI inter-operability
command-line options and/or opcodes to enable the use of ordinary Csound
instrument definitions to render external scores or MIDI sequences.

Note that Csound can connect to ALSA ports through Jack, but in that
case you will have to identify the port by its alias in the JackInfo
printout.

  Performance

The actual MIDI events will be received in the regular Csound way, i.e.
through a MIDI driver and the sensevents mechanism, rather than through
a Jack input port opcode.

The granularity of timing is Csound's kperiod.


===========================================================================
JackoMidiOutConnect                                     *JackoMidiOutConnect*

  Description

In the orchestra header, creates a connection from a Jack MIDI output
port inside this instance of Csound to an external Jack MIDI input port.

  Syntax

JackoMidiOutConnect ScsoundPortName, SexternalPortName

  Initialization

ScsoundPortName -- The short name ("portname") of the internal Jack MIDI
output port.

SexternalPortName -- The full name ("clientname:portname") of an
external Jack MIDI input port.

  Performance

The actual MIDI data must be written with the JackoMidiOut or
JackoNoteOut opcodes.


===========================================================================
JackoMidiOut                                                   *JackoMidiOut*

  Description

Sends a MIDI channel message to a Jack MIDI output port inside this
instance of Csound, and in turn to its connected external Jack MIDI
input port.

  Syntax

JackoMidiOut  ScsoundPortName, kstatus, kchannel, kdata1[, kdata2]

  Initialization

ScsoundPortName -- The short name ("portname") of the internal Jack MIDI
output port.

  Performance

kstatus -- MIDI status byte; must indicate a MIDI channel message.

kchannel -- MIDI channel (from 0 through 15).

kdata1 -- First data byte of a MIDI channel message.

kdata2 -- Optional second data byte of a MIDI channel message.

This opcode can be called any number of times in the same kperiod.
Messages from multiple instances of the opcode sending to the same port
are collected before sending.

Running status, system exclusive messages, and real-time messages are
not supported.

The granularity of timing is Csound's kperiod.


===========================================================================
JackoNoteOut                                                   *JackoNoteOut*

  Description

Sends a MIDI channel message to a Jack MIDI output port inside this
instance of Csound, and in turn to its connected external Jack MIDI
input port.

  Syntax

JackoNoteOut  ScsoundPortName, kstatus, kchannel, kdata1[, kdata2]

  Initialization

ScsoundPortName -- The short name ("portname") of the internal Jack MIDI
output port.

  Performance

kstatus -- MIDI status byte; must indicate a MIDI channel message.

kchannel -- MIDI channel (from 0 through 15).

kdata1 -- First data byte of a MIDI channel message.

kdata2 -- Optional second data byte of a MIDI channel message.

This opcode can be called any number of times in the same kperiod.
Messages from multiple instances of the opcode sending to the same port
are collected before sending.

Running status, system exclusive messages, and real-time messages are
not supported.

The granularity of timing is Csound's kperiod.


===========================================================================
JackoOn                                                             *JackoOn*

  Description

In the orchestra header, after all Jack connections have been created,
enables or disables all Jack input and output opcodes inside this
instance of Csound to read or write data.

  Syntax

JackoOn [iactive] 

  Initialization

iactive -- A flag that turns the ports on (the default) or off.


===========================================================================
JackoTransport                                               *JackoTransport*

  Description

Starts, stops, or repositions the Jack transport. This is useful, e.g.,
for starting an external sequencer playing to send MIDI messages to Csound.

  Syntax

JackoTransport  kcommand, [kposition]

  Performance

kcommand -- 0 means "no action", 1 starts the transport, 2 stops the
transport, and 3 positions the transport to kposition seconds from the
beginning of performance (i.e. time 0 in the score).

kposition -- Time to position to the transport, in seconds from the
beginning of performance (i.e. time 0 in the score).

This opcode can be used at init time or during performance.

The granularity of timing is Csound's kperiod.


===========================================================================
jacktransport                                                 *jacktransport*

  Description

Start/stop jack_transport and can optionally relocate the playback head.

  Syntax

jacktransport icommand [, ilocation]

  Initialization

icommand -- 1 to start playing, 0 to stop.

ilocation -- optional location in seconds to specify where the playback
head should be moved. If omitted, the transport is started from current
location.

  Note
Since jacktransport depends on jack audio connection kit, it will work
only on Linux or Mac OS X systems which have the jack server running.


===========================================================================
jitter                                                               *jitter*

  Description

Generates a segmented line whose segments are randomly generated.

  Syntax

kout jitter kamp, kcpsMin, kcpsMax

  Performance

kamp -- Amplitude of jitter deviation

kcpsMin -- Minimum speed of random frequency variations (expressed in cps)

kcpsMax -- Maximum speed of random frequency variations (expressed in cps)

jitter generates a segmented line whose segments are randomly generated
inside the +kamp and -kamp interval. Duration of each segment is a
random value generated according to kcpsmin and kcpsmax values.

jitter can be used to make more natural and “analog-sounding” some
static, dull sound. For best results, it is suggested to keep its
amplitude moderate.


===========================================================================
jitter2                                                             *jitter2*

  Description

Generates a segmented line with user-controllable random segments.

  Syntax

kout jitter2 ktotamp, kamp1, kcps1, kamp2, kcps2, kamp3, kcps3

  Performance

ktotamp -- Resulting amplitude of jitter2

kamp1 -- Amplitude of the first jitter component

kcps1 -- Speed of random variation of the first jitter component
(expressed in cps)

kamp2 -- Amplitude of the second jitter component

kcps2 -- Speed of random variation of the second jitter component
(expressed in cps)

kamp3 -- Amplitude of the third jitter component

kcps3 -- Speed of random variation of the third jitter component
(expressed in cps)

jitter2 also generates a segmented line such as jitter, but in this case
the result is similar to the sum of three randi opcodes, each one with a
different amplitude and frequency value (see randi for more details),
that can be varied at k-rate. Different effects can be obtained by
varying the input arguments.

jitter2 can be used to make more natural and “analog-sounding” some
static, dull sound. For best results, it is suggested to keep its
amplitude moderate.


===========================================================================
joystick                                                           *joystick*

  Description

Reads data from a Linux joystick controller

  Syntax

kres joystick kdevice ktab

  Performance

  Note

Please note that this opcode is currently only supported on Linux.

kdevice -- the index of the joystick device, either /dev/jsN or
/dev/input/jsN.

ktab -- A table to hold input results, should be at least enough
elements to store one value for each stick axis and one for each button
+ 2. The first two elements of the table are initialized with the number
of axes and the number of buttons, respectively, when a joystick is
opened. If a joystick is unplugged during performance, the opcode will
repeatedly attempt to reopen the device with a delay between attempts.


===========================================================================
jspline                                                             *jspline*

  Description

A jitter-spline generator.

  Syntax

ares jspline xamp, kcpsMin, kcpsMax

kres jspline kamp, kcpsMin, kcpsMax

  Performance

kres, ares -- Output signal

xamp -- Amplitude factor

kcpsMin, kcpsMax -- Range of point-generation rate. Min and max limits
are expressed in cps.

jspline (jitter-spline generator) generates a smooth curve based on
random points generated at [cpsMin, cpsMax] rate. This opcode is similar
to randomi or randi or jitter, but segments are not straight lines, but
cubic spline curves. Output value range is approximately > -xamp and <
xamp. Actually, real range could be a bit greater, because of
interpolating curves beetween each pair of random-points.

At present time generated curves are quite smooth when cpsMin is not too
different from cpsMax. When cpsMin-cpsMax interval is big, some little
discontinuity could occurr, but it should not be a problem, in most
cases. Maybe the algorithm will be improved in next versions.

These opcodes are often better than jitter when user wants to
“naturalize” or “analogize” digital sounds. They could be used also in
algorithmic composition, to generate smooth random melodic lines when
used together with samphold opcode.

Note that the result is quite different from the one obtained by
filtering white noise, and they allow the user to obtain a much more
precise control.


===========================================================================
k                                                                         *k*

  Description

Converts an i-rate value to control rate, for example to be used with
rnd() and birnd() to generate random numbers at k-rate.

  Syntax

k(x) (i-rate args only)

k(x) (a-rate args only)

where the argument within the parentheses may be an expression. Value
converters perform arithmetic translation from units of one kind to
units of another. The result can then be a term in a further expression.


===========================================================================
kgoto                                                                 *kgoto*

  Description

During the p-time passes only, unconditionally transfer control to the
statement labeled by label.

  Syntax

kgoto label

where label is in the same instrument block and is not an expression.


===========================================================================
kr                                                                       *kr*

  Description

These statements are global value assignments, made at the beginning of
an orchestra, before any instrument block is defined. Their function is
to set certain reserved symbol variables that are required for
performance. Once set, these reserved symbols can be used in expressions
anywhere in the orchestra.

  Syntax

kr = iarg

  Initialization

kr = (optional) -- set control rate to iarg samples per second. The
default value is 4410.

In addition, any global variable can be initialized by an init-time
assignment anywhere before the first instr statement. All of the above
assignments are run as instrument 0 (i-pass only) at the start of real
performance.

Beginning with Csound version 3.46, kr can be omitted. Csound will use
the default values, or calculate kr from defined ksmps and sr. It is
usually better to just specify ksmps and sr and let csound calculate kr.


===========================================================================
ksmps                                                                 *ksmps*

  Description

These statements are global value assignments, made at the beginning of
an orchestra, before any instrument block is defined. Their function is
to set certain reserved symbol variables that are required for
performance. Once set, these reserved symbols can be used in expressions
anywhere in the orchestra.

  Syntax

ksmps = iarg

  Initialization

ksmps = (optional) -- set the number of samples in a control period.
This value must equalsr/kr. The default value is 10.

In addition, any global variable can be initialized by an init-time
assignment anywhere before the first instr statement. All of the above
assignments are run as instrument 0 (i-pass only) at the start of real
performance.

Beginning with Csound version 3.46, either ksmps may be omitted. Csound
will attempt to calculate the omitted value from the specified sr and
krvalues, but it should evaluate to an integer.

  Warning

ksmps must be an integer value.


===========================================================================
lenarray                                                           *lenarray*

  Description

Evaluates the size or number of dimensions of an array.

  Syntax

ir lenarray karray[, iwhich]

kr lenarray karray[, iwhich]

  Initialisation

karray -- The array that is being questioned. It can be of any dimension.

iwhich -- selects which dimension to evaluate the size. If zero or
negative it selects the number of dimensions. It defaults to 1, as used
in a vector.

  Performance

kr -- length of vector.

karray -- array to query.

If the dimension requested is larger than the actual array, or the array
is not initialised the value -1 is returned.


===========================================================================
lfo                                                                     *lfo*

  Description

A low frequency oscillator of various shapes.

  Syntax

kres lfo kamp, kcps [, itype]

ares lfo kamp, kcps [, itype]

  Initialization

itype (optional, default=0) -- determine the waveform of the oscillator.
Default is 0.

  * itype = 0 - sine

  * itype = 1 - triangles

  * itype = 2 - square (bipolar)

  * itype = 3 - square (unipolar)

  * itype = 4 - saw-tooth

  * itype = 5 - saw-tooth(down)

The sine wave is implemented as a 4096 table and linear interpolation.
The others are calculated.

  Performance

kamp -- amplitude of output

kcps -- frequency of oscillator


===========================================================================
limit                                                                 *limit*

  Description

Sets the lower and upper limits of the value it processes.

  Syntax

ares limit asig, klow, khigh

ires limit isig, ilow, ihigh

kres limit ksig, klow, khigh

  Initialization

isig -- input signal

ilow -- low threshold

ihigh -- high threshold

  Performance

xsig -- input signal

klow -- low threshold

khigh -- high threshold

limit sets the lower and upper limits on the xsig value it processes. If
xhigh is lower than xlow, then the output will be the average of the two
- it will not be affected by xsig.

This opcode is useful in several situations, such as table indexing or
for clipping and modeling a-rate, i-rate or k-rate signals.


===========================================================================
line                                                                   *line*

  Description

Trace a straight line between specified points.

  Syntax

ares line ia, idur, ib

kres line ia, idur, ib

  Initialization

ia -- starting value.

ib -- value after idur seconds.

idur -- duration in seconds of segment. A zero or negative value will
cause all initialization to be skipped.

  Performance

line generates control or audio signals whose values move linearly from
an initial value to a final one.

  Note

A common error with this opcode is to assume that the value of ib is
held after the time idur1. line does not automatically end or stop at
the end of the duration given. If your note length is longer than idur
seconds, kres (or ares) will not come to rest at ib, but will instead
continue to rise or fall with the same rate. If a rise (or fall) and
then hold is required that the linseg opcode should be considered instead.


===========================================================================
linen                                                                 *linen*

  Description

linen -- apply a straight line rise and decay pattern to an input amp
signal.

  Syntax

ares linen xamp, irise, idur, idec

kres linen kamp, irise, idur, idec

  Initialization

irise -- rise time in seconds. A zero or negative value signifies no
rise modification.

idur -- overall duration in seconds. A zero or negative value will cause
initialization to be skipped.

idec -- decay time in seconds. Zero means no decay. An idec > idur will
cause a truncated decay.

  Performance

kamp, xamp -- input amplitude signal.

Rise modifications are applied for the first irise seconds, and decay
from time idur - idec. If these periods are separated in time there will
be a steady state during which amp will be unmodified. If linen rise and
decay periods overlap then both modifications will be in effect for that
time. If the overall duration idur is exceeded in performance, the final
decay will continue on in the same direction, going negative.

[Envelope generated by the linen opcode]

Envelope generated by the linen opcode

  Note

A common error with this opcode is to assume that the value of 0 is the
held after the envelope has finished at idur. linen does not
automatically end or stop at the end of the duration given. If your note
length is longer than idur seconds, kres (or ares) will not come to rest
at 0, but will instead continue to fall with the same rate. If a decay
and then hold is required then the linseg opcode should be considered
instead.


===========================================================================
linenr                                                               *linenr*

  Description

linenr -- same as linen except that the final segment is entered only on
sensing a MIDI note release. The note is then extended by the decay time.

  Syntax

ares linenr xamp, irise, idec, iatdec

kres linenr kamp, irise, idec, iatdec

  Initialization

irise -- rise time in seconds. A zero or negative value signifies no
rise modification.

idec -- decay time in seconds. Zero means no decay. An idec > idur will
cause a truncated decay.

iatdec -- attenuation factor by which the closing steady state value is
reduced exponentially over the decay period. This value must be positive
and is normally of the order of .01. A large or excessively small value
is apt to produce a cutoff which is audible. A zero or negative value is
illegal.

  Performance

kamp, xamp -- input amplitude signal.

linenr is unique within Csound in containing a note-off sensor and
release time extender. When it senses either a score event termination
or a MIDI noteoff, it will immediately extend the performance time of
the current instrument by idec seconds, then execute an exponential
decay towards the factor iatdec. For two or more units in an instrument,
extension is by the greatest idec.

You can use other pre-made envelopes which start a release segment upon
receiving a note off message, like linsegr and expsegr, or you can
construct more complex envelopes using xtratim and release. Note that
you don't need to use xtratim if you are using linenr, since the time is
extended automatically.

These “r” units can also be modified by MIDI noteoff velocities (see
veloffs).


===========================================================================
lineto                                                               *lineto*

  Description

Generate glissandos starting from a control signal.

  Syntax

kres lineto ksig, ktime

  Performance

kres -- Output signal.

ksig -- Input signal.

ktime -- Time length of glissando in seconds.

lineto adds glissando (i.e. straight lines) to a stepped input signal
(for example, produced by randh or lpshold). It generates a straight
line starting from previous step value, reaching the new step value in
ktime seconds. When the new step value is reached, such value is held
until a new step occurs. Be sure that ktime argument value is smaller
than the time elapsed between two consecutive steps of the original
signal, otherwise discontinuities will occur in output signal.

When used together with the output of lpshold it emulates the glissando
effect of old analog sequencers.

  Note

No new value for ksig or ktime will have effect until the previous ktime
has elapsed.


===========================================================================
linrand                                                             *linrand*

  Description

Linear distribution random number generator (positive values only). This
is an x-class noise generator.

  Syntax

ares linrand krange

ires linrand krange

kres linrand krange

  Performance

krange -- the range of the random numbers (0 - krange). Outputs only
positive numbers.

For more detailed explanation of these distributions, see:

 1. C. Dodge - T.A. Jerse 1985. Computer music. Schirmer books. pp.265 - 286

 2. D. Lorrain. A panoply of stochastic cannons. In C. Roads, ed. 1989.
    Music machine . Cambridge, Massachusetts: MIT press, pp. 351 - 379.


===========================================================================
linseg                                                               *linseg*

  Description

Trace a series of line segments between specified points.

  Syntax

ares linseg ia, idur1, ib [, idur2] [, ic] [...]

kres linseg ia, idur1, ib [, idur2] [, ic] [...]

  Initialization

ia -- starting value.

ib, ic, etc. -- value after dur1 seconds, etc.

idur1 -- duration in seconds of first segment. A zero or negative value
will cause all initialization to be skipped.

idur2, idur3, etc. -- duration in seconds of subsequent segments. A zero
or negative value will terminate the initialization process with the
preceding point, permitting the last-defined line or curve to be
continued indefinitely in performance. The default is zero.

  Performance

These units generate control or audio signals whose values can pass
through 2 or more specified points. The sum of dur values may or may not
equal the instrument's performance time: a shorter performance will
truncate the specified pattern, while a longer one will cause the last
value to be repeated until the end of the note.


===========================================================================
linsegb                                                             *linsegb*

  Description

Trace a series of line segments between specified absolute points.

  Syntax

ares linsegb ia, itim1, ib [, itim2] [, ic] [...]

kres linsegb ia, itim1, ib [, itim2] [, ic] [...]

  Initialization

ia -- starting value.

ib, ic, etc. -- value at tim1 seconds, etc.

itim1 -- time in seconds of end of first segment. A zero or negative
value will cause all initialization to be skipped.

itim2, itim3, etc. -- time in seconds at the end of subsequent segments.

  Performance

These units generate control or audio signals whose values can pass
through 2 or more specified points. The last tim value may or may not
equal the instrument's performance time: a shorter performance will
truncate the specified pattern, while a longer one will cause the last
value to be repeated until the end of the note.


===========================================================================
linsegr                                                             *linsegr*

  Description

Trace a series of line segments between specified points including a
release segment.

  Syntax

ares linsegr ia, idur1, ib [, idur2] [, ic] [...], irel, iz

kres linsegr ia, idur1, ib [, idur2] [, ic] [...], irel, iz

  Initialization

ia -- starting value.

ib, ic, etc. -- value after dur1 seconds, etc.

idur1 -- duration in seconds of first segment. A zero or negative value
will cause all initialization to be skipped.

idur2, idur3, etc. -- duration in seconds of subsequent segments. A zero
or negative value will terminate the initialization process with the
preceding point, permitting the last-defined line or curve to be
continued indefinitely in performance. The default is zero.

irel, iz -- duration in seconds and final value of a note releasing
segment.

For Csound versions prior to 5.00, the release time cannot be longer
than 32767/kr seconds. This limit has been extended to (2^31 -1)/kr.

  Performance

These units generate control or audio signals whose values can pass
through 2 or more specified points. The sum of dur values may or may not
equal the instrument's performance time: a shorter performance will
truncate the specified pattern, while a longer one will cause the
last-defined segment to continue on in the same direction.

linsegr is amongst the Csound “r” units that contain a note-off sensor
and release time extender. When each senses an event termination or MIDI
noteoff, it immediately extends the performance time of the current
instrument by irel seconds, and sets out to reach the value iz by the
end of that period (no matter which segment the unit is in). “r” units
can also be modified by MIDI noteoff velocities. For two or more
extenders in an instrument, extension is by the greatest period.

You can use other pre-made envelopes which start a release segment upon
receiving a note off message, like linenr and expsegr, or you can
construct more complex envelopes using xtratim and release. Note that
you don't need to use xtratim if you are using linsegr, since the time
is extended automatically.


===========================================================================
locsend                                                             *locsend*

  Description

locsend depends upon the existence of a previously defined locsig. The
number of output signals must match the number in the previous locsig.
The output signals from locsend are derived from the values given for
distance and reverb in the locsig and are ready to be sent to local or
global reverb units (see example below). The reverb amount and the
balance between the 2 or 4 channels are calculated in the same way as
described in the Dodge book (an essential text!).

  Syntax

a1, a2 locsend

a1, a2,  a3, a4 locsend


===========================================================================
locsig                                                               *locsig*

  Description

locsig takes an input signal and distributes it among 2 or 4 channels
using values in degrees to calculate the balance between adjacent
channels. It also takes arguments for distance (used to attenuate
signals that are to sound as if they are some distance further than the
loudspeaker itself), and for the amount the signal that will be sent to
reverberators. This unit is based upon the example in the Charles
Dodge/Thomas Jerse book, Computer Music, page 320.

  Syntax

a1, a2 locsig asig, kdegree, kdistance, kreverbsend

a1, a2,  a3, a4 locsig asig, kdegree, kdistance, kreverbsend

  Performance

kdegree -- value between 0 and 360 for placement of the signal in a 2 or
4 channel space configured as: a1=0, a2=90, a3=180, a4=270 (kdegree=45
would balanced the signal equally between a1 and a2). locsig maps
kdegree to sin and cos functions to derive the signal balances (e.g.:
asig=1, kdegree=45, a1=a2=.707).

kdistance -- value >= 1 used to attenuate the signal and to calculate
reverb level to simulate distance cues. As kdistance gets larger the
sound should get softer and somewhat more reverberant (assuming the use
of locsend in this case).

kreverbsend -- the percentage of the direct signal that will be factored
along with the distance and degree values to derive signal amounts that
can be sent to a reverb unit such as reverb, or reverb2.


===========================================================================
log                                                                     *log*

  Description

Returns the natural log of x (x positive only). In the case of an array
input, the operation can have an optional arbitrary base.

The argument value is restricted for log, log10, and sqrt.

  Syntax

log(x) (no rate restriction)

kout[]log kin[][,ibas]

where the argument within the parentheses may be an expression. Value
converters perform arithmetic translation from units of one kind to
units of another. The result can then be a term in a further expression.
In the case of an array input, ibas is the optional arbitrary base,
which defaults to e (natural log base).


===========================================================================
log10                                                                 *log10*

  Description

Returns the base 10 log of x (x positive only).

The argument value is restricted for log, log10, and sqrt.

  Syntax

log10(x) (no rate restriction)

where the argument within the parentheses may be an expression. Value
converters perform arithmetic translation from units of one kind to
units of another. The result can then be a term in a further expression.


===========================================================================
log2                                                                   *log2*

  Description

Returns the base 2 log of x (x positive only).

The argument value is restricted for log, log2, and sqrt.

  Syntax

log2(x) (no rate restriction)

where the argument within the parentheses may be an expression. Value
converters perform arithmetic translation from units of one kind to
units of another. The result can then be a term in a further expression.


===========================================================================
logbtwo                                                             *logbtwo*

  Description

Performs a logarithmic base two calculation.

  Syntax

logbtwo(x)  (init-rate or control-rate args only)

  Performance

logbtwo() returns the logarithm base two of x. The range of values
admitted as argument is .25 to 4 (i.e. from -2 octave to +2 octave
response). This function is the inverse of powoftwo().

These functions are fast, because they read values stored in tables.
Also they are very useful when working with tuning ratios. They work at
i- and k-rate.


===========================================================================
logcurve                                                           *logcurve*

  Description

Generates a logarithmic curve in range 0 to 1 of arbitrary steepness.
Steepness index equal to or lower than 1.0 will result in Not-a-Number
errors and cause unstable behavior.

The formula used to calculate the curve is:

log(x * (y-1)+1) / (log(y)

where x is equal to kindex and y is equal to ksteepness.

  Syntax

kout logcurve kindex, ksteepness

  Performance

kindex -- Index value. Expected range 0 to 1.

ksteepness -- Steepness of the generated curve. Values closer to 1.0
result in a straighter line while larger values steepen the curve.

kout -- Scaled output.


===========================================================================
loop_ge                                                             *loop_ge*

  Description

Construction of looping operations.

  Syntax

loop_ge  indx, idecr, imin, label

loop_ge  kndx, kdecr, kmin, label

  Initialization

indx -- i-rate variable to count loop.

idecr -- value to decrement the loop.

imin -- minimum value of loop index.

  Performance

kndx -- k-rate variable to count loop.

kdecr -- value to decrement the loop.

kmin -- minimum value of loop index.

The actions of loop_ge are equivalent to the code

         indx  =  indx - idecr
         if (indx >= imin) igoto label

or

         kndx  =  kndx - kdecr
         if (kndx >= kmin) kgoto label


===========================================================================
loop_gt                                                             *loop_gt*

  Description

Construction of looping operations.

  Syntax

loop_gt  indx, idecr, imin, label

loop_gt  kndx, kdecr, kmin, label

  Initialization

indx -- i-rate variable to count loop.

idecr -- value to decrement the loop.

imin -- minimum value of loop index.

  Performance

kndx -- k-rate variable to count loop.

kdecr -- value to decrement the loop.

kmin -- minimum value of loop index.

The actions of loop_gt are equivalent to the code

         indx  =  indx - idecr
         if (indx > imin) igoto label

or

         kndx  =  kndx - kdecr
         if (kndx > kmin) kgoto label


===========================================================================
loop_le                                                             *loop_le*

  Description

Construction of looping operations.

  Syntax

loop_le  indx, incr, imax, label

loop_le  kndx, kncr, kmax, label

  Initialization

indx -- i-rate variable to count loop.

incr -- value to increment the loop.

imax -- maximum value of loop index.

  Performance

kndx -- k-rate variable to count loop.

kncr -- value to increment the loop.

kmax -- maximum value of loop index.

The actions of loop_le are equivalent to the code

         indx  =  indx + incr
         if (indx <= imax) igoto label

or

         kndx  =  kndx + kncr
         if (kndx <= kmax) kgoto label


===========================================================================
loop_lt                                                             *loop_lt*

  Description

Construction of looping operations.

  Syntax

loop_lt  indx, incr, imax, label

loop_lt  kndx, kncr, kmax, label

  Initialization

indx -- i-rate variable to count loop.

incr -- value to increment the loop.

imax -- maximum value of loop index.

  Performance

kndx -- k-rate variable to count loop.

kncr -- value to increment the loop.

kmax -- maximum value of loop index.

The actions of loop_lt are equivalent to the code

         indx  =  indx + incr
         if (indx < imax) igoto label

or

         kndx  =  kndx + kncr
         if (kndx < kmax) kgoto label


===========================================================================
loopseg                                                             *loopseg*

  Description

Generate control signal consisting of linear segments delimited by two
or more specified points. The entire envelope is looped at kfreq rate.
Each parameter can be varied at k-rate.

  Syntax

ksig loopseg kfreq, ktrig, iphase, kvalue0, ktime0 [, kvalue1] [, ktime1] \
[, kvalue2] [, ktime2][...]

  Initialization

iphase -- A value between 0 and 1 to say where to start the loop. Zero,
the commonest value, indicates the beginning.

  Performance

ksig -- Output signal.

kfreq -- Repeat rate in Hz or fraction of Hz.

ktrig -- If non-zero, retriggers the envelope from start (see trigger
opcode), before the envelope cycle is completed.

kvalue0...kvalueN -- Values of points

ktime0...ktimeN -- Times between points; expressed in fractions of a
cycle (see below). The final time designates a ramp between the final
value and the first value.

loopseg opcode is similar to linseg, but the entire envelope is looped
at kfreq rate. Notice that times are not expressed in seconds but in
fraction of a cycle. Actually each duration represent is proportional to
the other, and the entire cycle duration is proportional to the sum of
all duration values.

The sum of all duration is then rescaled according to kfreq argument.
For example, considering an envelope made up of 3 segments, each segment
having 100 as duration value, their sum will be 300. This value
represents the total duration of the envelope, and is actually divided
into 3 equal parts, a part for each segment.

Actually, the real envelope duration in seconds is determined by kfreq.
Again, if the envelope is made up of 3 segments, but this time the first
and last segments have a duration of 50, whereas the central segment has
a duration of 100 again, their sum will be 200. This time 200 represent
the total duration of the 3 segments, so the central segment will be
twice as long as the other segments.

All parameters can be varied at k-rate. Negative frequency values are
allowed, reading the envelope backward. ktime0 should always be set to
0, except if the user wants some special effect.


===========================================================================
loopsegp                                                           *loopsegp*

  Description

Generate control signal consisiting of linear segments delimited by two
or more specified points. The entire envelope can be looped at
time-variant rate. Each segment coordinate can also be varied at k-rate.

  Syntax

ksig loopsegp  kphase, kvalue0, kdur0, kvalue1 \
      [, kdur1, ... , kdurN-1, kvalueN]

  Performance

ksig - output signal

kphase - point of the sequence read, expressed as a fraction of a cycle
(0 to 1)

kvalue0 ...kvalueN - values of points

kdur0 ...kdurN-1 - duration of points expessed in fraction of a cycle

loopsegp opcode is similar to loopseg; the only difference is that,
instead of frequency, a time-variant phase is required. If you use
phasor to get the phase value, you will have a behaviour identical to
loopseg, but interesting results can be achieved when using phases
having non-linear motions, making loopsegp more powerful and general
than loopseg.


===========================================================================
looptseg                                                           *looptseg*

  Description

Generate control signal consisting of controllable exponential segments
or linear segments delimited by two or more specified points. The entire
envelope is looped at kfreq rate. Each parameter can be varied at k-rate.

  Syntax

ksig looptseg kfreq, ktrig, iphase, kvalue0, ktype0, ktime0, [, kvalue1] [,ktype1] [, ktime1] \
      [, kvalue2] [,ktype2] [, ktime2] [...] [, kvalueN] [,ktypeN] [, ktimeN]

  Initialization

iphase -- A value between 0 and 1 to say where to start the loop. Zero,
the commonest value, indicates the beginning.

  Performance

ksig -- Output signal.

kfreq -- Repeat rate in Hz or fraction of Hz.

ktrig -- If non-zero, retriggers the envelope from start (see trigger
opcode), before the envelope cycle is completed.

kvalue0...kvalueN -- Values of points

ktime0...ktimeN -- Times between points; expressed in fractions of a
cycle (see below). The final time designates a ramp between the final
value and the first value.

ktype0...ktypeN -- shape of the envelope. If the value is 0 then the
shap eis linear; otherwise it is an concave exponential (positive type)
or a convex exponential (negative type).

looptseg opcode is similar to transeg, but the entire envelope is looped
at kfreq rate. Notice that times are not expressed in seconds but in
fraction of a cycle. Actually each duration represent is proportional to
the other, and the entire cycle duration is proportional to the sum of
all duration values.

The sum of all duration is then rescaled according to kfreq argument.
For example, considering an envelope made up of 3 segments, each segment
having 100 as duration value, their sum will be 300. This value
represents the total duration of the envelope, and is actually divided
into 3 equal parts, a part for each segment.

Actually, the real envelope duration in seconds is determined by kfreq.
Again, if the envelope is made up of 3 segments, but this time the first
and last segments have a duration of 50, whereas the central segment has
a duration of 100 again, their sum will be 200. This time 200 represent
the total duration of the 3 segments, so the central segment will be
twice as long as the other segments.

All parameters can be varied at k-rate. Negative frequency values are
allowed, reading the envelope backward. ktime0 should always be set to
0, except if the user wants some special effect.


===========================================================================
loopxseg                                                           *loopxseg*

  Description

Generate control signal consisting of exponential segments delimited by
two or more specified points. The entire envelope is looped at kfreq
rate. Each parameter can be varied at k-rate.

  Syntax

ksig loopxseg kfreq, ktrig, iphase, ktime0, kvalue0 [, ktime1] [, kvalue1] \
      [, ktime2] [, kvalue2] [...]

  Performance

ksig -- Output signal.

kfreq -- Repeat rate in Hz or fraction of Hz.

ktrig -- If non-zero, retriggers the envelope from start (see trigger
opcode), before the envelope cycle is completed.

iphase -- A value between 0 and 1 to say where to start the loop. Zero,
the commonest value, indicates the beginning.

ktime0...ktimeN -- Times of points; expressed in fraction of a cycle.

kvalue0...kvalueN -- Values of points

loopxseg opcode is similar to expseg, but the entire envelope is looped
at kfreq rate. Notice that times are not expressed in seconds but in
fraction of a cycle. Actually each duration represent is proportional to
the other, and the entire cycle duration is proportional to the sum of
all duration values.

The sum of all duration is then rescaled according to kfreq argument.
For example, considering an envelope made up of 3 segments, each segment
having 100 as duration value, their sum will be 300. This value
represents the total duration of the envelope, and is actually divided
into 3 equal parts, a part for each segment.

Actually, the real envelope duration in seconds is determined by kfreq.
Again, if the envelope is made up of 3 segments, but this time the first
and last segments have a duration of 50, whereas the central segment has
a duration of 100 again, their sum will be 200. This time 200 represent
the total duration of the 3 segments, so the central segment will be
twice as long as the other segments.

All parameters can be varied at k-rate. Negative frequency values are
allowed, reading the envelope backward. ktime0 should always be set to
0, except if the user wants some special effect.


===========================================================================
lorenz                                                               *lorenz*

  Description

Implements the Lorenz system of equations. The Lorenz system is a
chaotic-dynamic system which was originally used to simulate the motion
of a particle in convection currents and simplified weather systems.
Small differences in initial conditions rapidly lead to diverging
values. This is sometimes expressed as the butterfly effect. If a
butterfly flaps its wings in Australia, it will have an effect on the
weather in Alaska. This system is one of the milestones in the
development of chaos theory. It is useful as a chaotic audio source or
as a low frequency modulation source.

  Syntax

ax, ay, az lorenz ksv, krv, kbv, kh, ix, iy, iz, iskip [, iskipinit]

  Initialization

ix, iy, iz -- the initial coordinates of the particle.

iskip -- used to skip generated values. If iskip is set to 5, only every
fifth value generated is output. This is useful in generating higher
pitched tones.

iskipinit (optional, default=0) -- if non zero skip the initialisation
of the filter. (New in Csound version 4.23f13 and 5.0)

  Performance

ksv -- the Prandtl number or sigma

krv -- the Rayleigh number

kbv -- the ratio of the length and width of the box in which the
convection currents are generated

kh -- the step size used in approximating the differential equation.
This can be used to control the pitch of the systems. Values of .1-.001
are typical.

The equations are approximated as follows:

x = x + h*(s*(y - x))
y = y + h*(-x*z + r*x - y)
z = z + h*(x*y - b*z)

The historical values of these parameters are:

ks = 10
kr = 28
kb = 8/3

  Note

This algorithm uses internal non linear feedback loops which causes
audio result to depend on the orchestra sampling rate. For example, if
you develop a project with sr=48000Hz and if you want to produce an
audio CD from it, you should record a file with sr=48000Hz and then
downsample the file to 44100Hz using the srconv utility.


===========================================================================
lorisread                                                         *lorisread*

  Syntax

lorisread ktimpnt, ifilcod, istoreidx, kfreqenv, kampenv, kbwenv[, ifadetime]

  Description

lorisread imports a set of bandwidth-enhanced partials from a
SDIF-format data file, applying control-rate frequency, amplitude, and
bandwidth scaling envelopes, and stores the modified partials in memory.

  Initialization

ifilcod - integer or character-string denoting a control-file derived
from reassigned bandwidth-enhanced analysis of an audio signal. An
integer denotes the suffix of a file loris.sdif (e.g. loris.sdif.1); a
character-string (in double quotes) gives a filename, optionally a full
pathname. If not a full pathname, the file is sought first in the
current directory, then in the one given by the environment variable
SADIR (if defined). The reassigned bandwidth-enhanced data file contains
breakpoint frequency, amplitude, noisiness, and phase envelope values
organized for bandwidth-enhanced additive resynthesis. The control data
must conform to one of the SDIF formats that can be

Loris stores partials in SDIF RBEP frames. Each RBEP frame contains one
RBEP matrix, and each row in a RBEP matrix describes one breakpoint in a
Loris partial. A RBEL frame containing one RBEL matrix describing the
labeling of the partials may precede the first RBEP frame in the SDIF
file. The RBEP and RBEL frame and matrix definitions are included in the
SDIF file's header. In addition to RBEP frames, Loris can also read and
write SDIF 1TRC frames. Since 1TRC frames do not represent
bandwidth-enhancement or the exact timing of Loris breakpoints, their
use is not recommended. 1TRC capabilities are provided to allow
interchange with programs that are unable to handle RBEP frames.

istoreidx, ireadidx, isrcidx, itgtidx are labels that identify a stored
set of bandwidth-enhanced partials. lorisread imports partials from a
SDIF file and stores them with the integer label istoreidx. lorismorph
morphs sets of partials labeled isrcidx and itgtidx, and stores the
resulting partials with the integer label istoreidx. lorisplay renders
the partials stored with the label ireadidx. The labels are used only at
initialization time, and may be reused without any cost or benefit in
efficiency, and without introducing any interaction between instruments
or instances.

ifadetime (optional) - In general, partials exported from Loris begin
and end at non-zero amplitude. In order to prevent artifacts, it is very
often necessary to fade the partials in and out, instead of turning them
abruptly on and off. Specification of a non-zero ifadetime causes
partials to fade in at their onsets and to fade out at their
terminations. This is achieved by adding two more breakpoints to each
partial: one ifadetime seconds before the start time and another
ifadetime seconds after the end time. (However, no breakpoint will be
introduced at a time less than zero. If necessary, the onset fade time
will be shortened.) The additional breakpoints at the partial onset and
termination will have the same frequency and bandwidth as the first and
last breakpoints in the partial, respectively, but their amplitudes will
be zero. The phase of the new breakpoints will be extrapolated to
preserve phase correctness. If no value is specified, ifadetime defaults
to zero. Note that the fadetime may not be exact, since the partial
parameter envelopes are sampled at the control rate (krate) and indexed
by ktimpnt (see below), and not by real time.

  Performance

lorisread reads pre-computed Reassigned Bandwidth-Enhanced analysis data
from a file stored in SDIF format, as described above. The passage of
time through this file is specified by ktimpnt, which represents the
time in seconds. ktimpnt must always be positive, but can move forwards
or backwards in time, be stationary or discontinuous, as a pointer into
the analysis file. kfreqenv is a control-rate transposition factor: a
value of 1 incurs no transposition, 1.5 transposes up a perfect fifth,
and .5 down an octave. kampenv is a control-rate scale factor that is
applied to all partial amplitude envelopes. kbwenv is a control-rate
scale factor that is applied to all partial bandwidth or noisiness
envelopes. The bandwidth-enhanced partial data is stored in memory with
a specified label for future access by another generator.


===========================================================================
lorismorph                                                       *lorismorph*

  Syntax

lorismorph isrcidx, itgtidx, istoreidx, kfreqmorphenv, kampmorphenv, kbwmorphenv

  Description

lorismorph morphs two stored sets of bandwidth-enhanced partials and
stores a new set of partials representing the morphed sound. The morph
is performed by linearly interpolating the parameter envelopes
(frequency, amplitude, and bandwidth, or noisiness) of the
bandwidth-enhanced partials according to control-rate frequency,
amplitude, and bandwidth morphing functions.

  Initialization

istoreidx, ireadidx, isrcidx, itgtidx are labels that identify a stored
set of bandwidth-enhanced partials. lorisread imports partials from a
SDIF file and stores them with the integer label istoreidx. lorismorph
morphs sets of partials labeled isrcidx and itgtidx, and stores the
resulting partials with the integer label istoreidx. lorisplay renders
the partials stored with the label ireadidx. The labels are used only at
initialization time, and may be reused without any cost or benefit in
efficiency, and without introducing any interaction between instruments
or instances.

  Performance

lorismorph generates a set of bandwidth-enhanced partials by morphing
two stored sets of partials, the source and target partials, which may
have been imported using lorisread, or generated by another unit
generator, including another instance of lorismorph. The morph is
performed by interpolating the parameters of corresponding (labeled)
partials in the two source sounds. The sound morph is described by three
control-rate morphing envelopes. kfreqmorphenv describes the
interpolation of partial frequency values in the two source sounds. When
kfreqmorphenv is 0, partial frequencies are obtained from the partials
stored at isrcidx. When kfreqmorphenv is 1, partial frequencies are
obtained from the partials at itgtidx. When kfreqmorphenv is between 0
and 1, the partial frequencies are interpolated between corresponding
source and target partials. Interpolation of partial amplitudes and
bandwidth (noisiness) coefficients are similarly described by
kampmorphenv and kbwmorphenv.


===========================================================================
lorisplay                                                         *lorisplay*

  Syntax

ar lorisplay ireadidx, kfreqenv, kampenv, kbwenv

  Description

lorisplay renders a stored set of bandwidth-enhanced partials using the
method of Bandwidth-Enhanced Additive Synthesis implemented in the Loris
software, applying control-rate frequency, amplitude, and bandwidth
scaling envelopes.

  Initialization

istoreidx, ireadidx, isrcidx, itgtidx are labels that identify a stored
set of bandwidth-enhanced partials. lorisread imports partials from a
SDIF file and stores them with the integer label istoreidx. lorismorph
morphs sets of partials labeled isrcidx and itgtidx, and stores the
resulting partials with the integer label istoreidx. lorisplay renders
the partials stored with the label ireadidx. The labels are used only at
initialization time, and may be reused without any cost or benefit in
efficiency, and without introducing any interaction between instruments
or instances.

  Performance

lorisplay implements signal reconstruction using Bandwidth-Enhanced
Additive Synthesis. The control data is obtained from a stored set of
bandwidth-enhanced partials imported from an SDIF file using lorisread
or constructed by another unit generator such as lorismorph. kfreqenv is
a control-rate transposition factor: a value of 1 incurs no
transposition, 1.5 transposes up a perfect fifth, and .5 down an octave.
kampenv is a control-rate scale factor that is applied to all partial
amplitude envelopes. kbwenv is a control-rate scale factor that is
applied to all partial bandwidth or noisiness envelopes. The
bandwidth-enhanced partial data is stored in memory with a specified
label for future access by another generator.


===========================================================================
loscil                                                               *loscil*

  Description

Read sampled sound (mono or stereo) from a table, with optional sustain
and release looping.

  Syntax

ar1 [,ar2] loscil xamp, kcps, ifn [, ibas] [, imod1] [, ibeg1] [, iend1] \
      [, imod2] [, ibeg2] [, iend2]

  Initialization

ifn -- function table number, typically denoting an sampled sound
segment with prescribed looping points loaded using GEN01. The source
file may be mono or stereo.

ibas (optional) -- base frequency in Hz of the recorded sound. This
optionally overrides the frequency given in the audio file, but is
required if the file did not contain one. The default value is 261.626
Hz, i.e. middle C. (New in Csound 4.03). If this value is not known or
not present, use 1 here and in kcps.

imod1, imod2 (optional, default=-1) -- play modes for the sustain and
release loops. A value of 1 denotes normal looping, 2 denotes forward &
backward looping, 0 denotes no looping. The default value (-1) will
defer to the mode and the looping points given in the source file. Make
sure you select an appropriate mode if the file does not contain this
information.

ibeg1, iend1, ibeg2, iend2 (optional, dependent on mod1, mod2) -- begin
and end points of the sustain and release loops. These are measured in
sample frames from the beginning of the file, so will look the same
whether the sound segment is monaural or stereo. If no loop points are
specified, and a looping mode (imod1, imod2) is given, the file will be
looped for the whole length.

  Performance

ar1, ar2 -- the output at audio-rate. There is just ar1 for mono output.
However, there is both ar1 and ar2 for stereo output.

xamp -- the amplitude of the output signal.

kcps -- the frequency of the output signal in cycles per second.

loscil samples the ftable audio at a rate determined by kcps, then
multiplies the result by xamp. The sampling increment for kcps is
dependent on the table's base-note frequency ibas, and is automatically
adjusted if the orchestra sr value differs from that at which the source
was recorded. In this unit, ftable is always sampled with interpolation.

If sampling reaches the sustain loop endpoint and looping is in effect,
the point of sampling will be modified and loscil will continue reading
from within that loop segment. Once the instrument has received a
turnoff signal (from the score or from a MIDI noteoff event), the next
sustain endpoint encountered will be ignored and sampling will continue
towards the release loop end-point, or towards the last sample
(henceforth to zeros).

loscil is the basic unit for building a sampling synthesizer. Given a
sufficient set of recorded piano tones, for example, this unit can
resample them to simulate the missing tones. Locating the sound source
nearest a desired pitch can be done via table lookup. Once a sampling
instrument has begun, its turnoff point may be unpredictable and require
an external release envelope; this is often done by gating the sampled
audio with linenr, which will extend the duration of a turned-off
instrument by a specific period while it implements a decay.

If you want to loop the whole file, specify a looping mode in imod1 and
do not enter any values for ibeg and iend.

[Caution]       Note to Windows users

Windows users typically use back-slashes, “\”, when specifying the paths
of their files. As an example, a Windows user might use the path
“c:\music\samples\loop001.wav”. This is problematic because back-slashes
are normally used to specify special characters.

To correctly specify this path in Csound, one may alternately:

  * Use forward slashes: c:/music/samples/loop001.wav

  * Use back-slash special characters, “\\”: c:\\music\\samples\\loop001.wav

  Note

This is mono loscil:

a1 loscil 10000, 1, 1, 1 ,1

...and this is stereo loscil:

a1, a2 loscil 10000, 1, 1, 1 ,1


===========================================================================
loscil3                                                             *loscil3*

  Description

Read sampled sound (mono or stereo) from a table, with optional sustain
and release looping, using cubic interpolation.

  Syntax

ar1 [,ar2] loscil3 xamp, kcps, ifn [, ibas] [, imod1] [, ibeg1] [, iend1] \
      [, imod2] [, ibeg2] [, iend2]

  Initialization

ifn -- function table number, typically denoting an sampled sound
segment with prescribed looping points loaded using GEN01. The source
file may be mono or stereo.

ibas (optional) -- base frequency in Hz of the recorded sound. This
optionally overrides the frequency given in the audio file, but is
required if the file did not contain one. The default value is 261.626
Hz, i.e. middle C. (New in Csound 4.03). If this value is not known or
not present, use 1 here and in kcps.

imod1, imod2 (optional, default=-1) -- play modes for the sustain and
release loops. A value of 1 denotes normal looping, 2 denotes forward &
backward looping, 0 denotes no looping. The default value (-1) will
defer to the mode and the looping points given in the source file. Make
sure you select an appropriate mode if the file does not contain this
information.

ibeg1, iend1, ibeg2, iend2 (optional, dependent on mod1, mod2) -- begin
and end points of the sustain and release loops. These are measured in
sample frames from the beginning of the file, so will look the same
whether the sound segment is monaural or stereo. If no loop points are
specified, and a looping mode (imod1, imod2) is given, the file will be
looped for the whole length.

  Performance

ar1, ar2 -- the output at audio-rate. There is just ar1 for mono output.
However, there is both ar1 and ar2 for stereo output.

xamp -- the amplitude of the output signal.

kcps -- the frequency of the output signal in cycles per second.

loscil3 is identical to loscil except that it uses cubic interpolation.
New in Csound version 3.50.

[Caution]       Note to Windows users

Windows users typically use back-slashes, “\”, when specifying the paths
of their files. As an example, a Windows user might use the path
“c:\music\samples\loop001.wav”. This is problematic because back-slashes
are normally used to specify special characters.

To correctly specify this path in Csound, one may alternately:

  * Use forward slashes: c:/music/samples/loop001.wav

  * Use back-slash special characters, “\\”: c:\\music\\samples\\loop001.wav

  Note

This is mono loscil3:

a1 loscil3 10000, 1, 1, 1, 1

...and this is stereo loscil3:

a1, a2 loscil3 10000, 1, 1, 1, 1


===========================================================================
loscilx                                                             *loscilx*

  Description

Read sampled sound (up to 16 channels) from a table, with optional
sustain and release looping.

  Syntax

ar1 [, ar2, ar3, ar4, ar5, ar6, ar7, ar8, ar9, ar10, ar11, ar12, ar13, ar14, \
      ar15, ar16] loscilx xamp, kcps, ifn \
      [, iwsize, ibas, istrt, imod, ibeg, iend]

  Initialization

ifn -- function table number, typically denoting an sampled sound
segment with prescribed looping points loaded using GEN01. The source
file may have up to 16 channels.

iwsize (optional) -- window size used in interpolation. iwsize
(optional, defaults to zero) -- interpolation window size, in samples.
Can be one of the following:

  * 1: round to nearest sample (no interpolation, for kpitch=1)

  * 2: linear interpolation

  * 4: cubic interpolation

  * >= 8: iwsize point sinc interpolation with anti-aliasing (slow)

Zero or negative values select the default, which is cubic interpolation.

ibas (optional) -- base frequency in Hz of the recorded sound. This
optionally overrides the frequency given in the audio file, but is
required if the file did not contain one. The default value is 261.626
Hz, i.e. middle C. (New in Csound 4.03). If this value is not known or
not present, use 1 here and in kcps.

istrt (optional, default 0) -- Frame to start reading the data. If this
is not an integer the the data is interpolated (see iwsize).

imod (optional, default -1) -- play mode for the sustain and release
loops. A value of 1 denotes normal looping, 2 denotes forward & backward
looping, 0 denotes no looping. The default value (-1) will defer to the
mode and the looping points given in the source file. Make sure you
select an appropriate mode if the file does not contain this information.

ibeg, iend (optional, depending on imod) -- begin and end points of the
sustain and release loops. These are measured in sample frames from the
beginning of the file. If no loop points are specified, and a looping
mode (imod is given, the file will be looped for the whole length.

  Performance

ar1, ar2, ... -- the output at audio-rate. The number of outputs must
match the number of channels in the sample file.

xamp -- the amplitude of the output signal.

kcps -- the factor to read the file. For example, a value of 1 has no
pitch change, 1.5 is up a fifth and 2 an octave.

loscilx samples the ftable audio at a rate determined by kcps, then
multiplies the result by xamp. The sampling increment for kcps is
dependent on the table's base-note frequency ibas, and is automatically
adjusted if the orchestra sr value differs from that at which the source
was recorded. In this unit, ftable is always sampled with interpolation.

If sampling reaches the sustain loop endpoint and looping is in effect,
the point of sampling will be modified and loscil will continue reading
from within that loop segment. Once the instrument has received a
turnoff signal (from the score or from a MIDI noteoff event), the next
sustain endpoint encountered will be ignored and sampling will continue
towards the release loop end-point, or towards the last sample
(henceforth to zeros).

If you want to loop the whole file, specify a looping mode in imod and
do not enter any values for ibeg and iend.


===========================================================================
lowpass2                                                           *lowpass2*

  Description

Implementation of a resonant second-order lowpass filter.

  Syntax

ares lowpass2 asig, kcf, kq [, iskip]

  Initialization

iskip -- initial disposition of internal data space. A zero value will
clear the space; a non-zero value will allow previous information to
remain. The default value is 0.

  Performance

asig -- input signal to be filtered

kcf -- cutoff or resonant frequency of the filter, measured in Hz

kq -- Q of the filter, defined, for bandpass filters, as
bandwidth/cutoff. kq should be between 1 and 500

lowpass2 is a second order IIR lowpass filter, with k-rate controls for
cutoff frequency (kcf) and Q (kq). As kq is increased, a resonant peak
forms around the cutoff frequency, transforming the lowpass filter
response into a response that is similar to a bandpass filter, but with
more low frequency energy. This corresponds to an increase in the
magnitude and "sharpness" of the resonant peak. For high values of kq, a
scaling function such as balance may be required. In practice, this
allows for the simulation of the voltage-controlled filters of analog
synthesizers, or for the creation of a pitch of constant amplitude while
filtering white noise.


===========================================================================
lowres                                                               *lowres*

  Description

lowres is a resonant lowpass filter.

  Syntax

ares lowres asig, kcutoff, kresonance [, iskip]

  Initialization

iskip -- initial disposition of internal data space. A zero value will
clear the space; a non-zero value will allow previous information to
remain. The default value is 0.

  Performance

asig -- input signal

kcutoff -- filter cutoff frequency point

kresonance -- resonance amount

lowres is a resonant lowpass filter derived from a Hans Mikelson
orchestra. This implementation is much faster than implementing it in
Csound language, and it allows kr lower than sr. kcutoff is not in Hz
and kresonance is not in dB, so experiment for the finding best results.


===========================================================================
lowresx                                                             *lowresx*

  Description

lowresx is equivalent to more layers of lowres with the same arguments
serially connected.

  Syntax

ares lowresx asig, xcutoff, xresonance [, inumlayer] [, iskip]

  Initialization

inumlayer -- number of elements in a lowresx stack. Default value is 4.
There is no maximum.

iskip -- initial disposition of internal data space. A zero value will
clear the space; a non-zero value will allow previous information to
remain. The default value is 0.

  Performance

asig -- input signal

xcutoff -- filter cutoff frequency point

xresonance -- resonance amount

lowresx is equivalent to more layer of lowres with the same arguments
serially connected. Using a stack of a larger number of filters allows a
sharper cutoff. This is faster than using a larger number of instances
of lowres in a Csound orchestra because only one initialization and k
cycle are needed at time and the audio loop falls entirely inside the
cache memory of processor. Based on an orchestra by Hans Mikelson


===========================================================================
lpf18                                                                 *lpf18*

  Description

Implementation of a 3 pole sweepable resonant lowpass filter.

  Syntax

ares lpf18 asig, xfco, xres, xdist [, iskip]

  Initialization

iskip (optional, default=0) -- Skip initialization if present and non-zero.

  Performance

xfco -- the filter cutoff frequency in Hz. Should be in the range 0 to
sr/2.

xres -- the amount of resonance. Self-oscillation occurs when xres is
approximately 1. Should usually be in the range 0 to 1, however, values
slightly greater than 1 are possible for more sustained oscillation and
an “overdrive” effect.

xdist -- amount of distortion. kdist = 0 gives a clean output. xdist > 0
adds tanh() distortion controlled by the filter parameters, in such a
way that both low cutoff and high resonance increase the distortion
amount. Some experimentation is encouraged.

lpf18 is a digital emulation of a 3 pole (18 dB/oct.) lowpass filter
capable of self-oscillation with a built-in distortion unit. It is
really a 3-pole version of moogvcf, retuned, recalibrated and with some
performance improvements. The tuning and feedback tables use no more
than 6 adds and 6 multiplies per control rate. The distortion unit,
itself, is based on a modified tanh function driven by the filter controls.

  Note

Before version 6.04 this filter requires that the input signal be
normalized to one.


===========================================================================
lpfreson                                                           *lpfreson*

  Description

Resynthesises a signal from the data passed internally by a previous
lpread, applying formant shifting.

  Syntax

ares lpfreson asig, kfrqratio

  Performance

asig -- an audio driving function for resynthesis.

kfrqratio -- frequency ratio. Must be greater than 0.

lpfreson receives values internally produced by a leading lpread.lpread
gets its values from the control file according to the input value
ktimpnt (in seconds). If ktimpnt proceeds at the analysis rate,
time-normal synthesis will result; proceeding at a faster, slower, or
variable rate will result in time-warped synthesis. At each k-period,
lpread interpolates between adjacent frames to more accurately determine
the parameter values (presented as output) and the filter coefficient
settings (passed internally to a subsequent lpreson).

The error signal kerr (between 0 and 1) derived during predictive
analysis reflects the deterministic/random nature of the analyzed
source. This will emerge low for pitched (periodic) material and higher
for noisy material. The transition from voiced to unvoiced speech, for
example, produces an error signal value of about .3. During synthesis,
the error signal value can be used to determine the nature of the
lpreson driving function: for example, by arbitrating between pitched
and non-pitched input, or even by determining a mix of the two. In
normal speech resynthesis, the pitched input to lpreson is a wideband
periodic signal or pulse train derived from a unit such as buzz, and the
nonpitched source is usually derived from rand. However, any audio
signal can be used as the driving function, the only assumption of the
analysis being that it has a flat response.

lpfreson is a formant shifted lpreson, in which kfrqratio is the (cps)
ratio of shifted to original formant positions. This permits synthesis
in which the source object changes its apparent acoustic size. lpfreson
with kfrqratio = 1 is equivalent to lpreson.

Generally, lpreson provides a means whereby the time-varying content and
spectral shaping of a composite audio signal can be controlled by the
dynamic spectral content of another. There can be any number of
lpread/lpreson (or lpfreson) pairs in an instrument or in an orchestra;
they can read from the same or different control files independently.


===========================================================================
lphasor                                                             *lphasor*

  Description

This opcode can be used to generate table index for sample playback
(e.g. tablexkt).

  Syntax

ares lphasor xtrns [, ilps] [, ilpe] [, imode] [, istrt] [, istor]

  Initialization

ilps -- loop start.

ilpe -- loop end (must be greater than ilps to enable looping). The
default value of ilps and ilpe is zero.

imode (optional: default = 0) -- loop mode. Allowed values are:

  * 0: no loop

  * 1: forward loop

  * 2: backward loop

  * 3: forward-backward loop

istrt (optional: default = 0) -- The initial output value (phase). It
must be less than ilpe if looping is enabled, but is allowed to be
greater than ilps (i.e. you can start playback in the middle of the loop).

istor (optional: default = 0) -- skip initialization if set to any
non-zero value.

  Performance

ares -- a raw table index in samples (same unit for loop points). Can be
used as index with the table opcodes.

xtrns -- transpose factor, expressed as a playback ratio. ares is
incremented by this value, and wraps around loop points. For example,
1.5 means a fifth above, 0.75 means fourth below. It is not allowed to
be negative.


===========================================================================
lpinterp                                                           *lpinterp*

  Description

Computes a new set of poles from the interpolation between two analysis.

  Syntax

lpinterp islot1, islot2, kmix

  Initialization

islot1 -- slot where the first analysis was stored

islot2 -- slot where the second analysis was stored

kmix -- mix value between the two analysis. Should be between 0 and 1. 0
means analysis 1 only. 1 means analysis 2 only. Any value in between
will produce interpolation between the filters.

lpinterp computes a new set of poles from the interpolation between two
analysis. The poles will be stored in the current lpslot and used by the
next lpreson opcode.


===========================================================================
lposcil                                                             *lposcil*

  Description

Read sampled sound (mono or stereo) from a table, with looping, and high
precision.

  Syntax

ares lposcil kamp, kfreqratio, kloop, kend, ifn [, iphs]

  Initialization

ifn -- function table number

  Performance

kamp -- amplitude

kfreqratio -- multiply factor of table frequency (for example: 1 =
original frequency, 1.5 = a fifth up , .5 = an octave down)

kloop -- start loop point (in samples)

kend -- end loop point (in samples)

lposcil (looping precise oscillator) allows varying at k-rate, the
starting and ending point of a sample contained in a table (GEN01). This
can be useful when reading a sampled loop of a wavetable, where repeat
speed can be varied during the performance.


===========================================================================
lposcil3                                                           *lposcil3*

  Description

Read sampled sound (mono or stereo) from a table, with looping, and high
precision. lposcil3 uses cubic interpolation.

  Syntax

ares lposcil3 kamp, kfreqratio, kloop, kend, ifn [, iphs]

  Initialization

ifn -- function table number

  Performance

kamp -- amplitude

kfreqratio -- multiply factor of table frequency (for example: 1 =
original frequency, 1.5 = a fifth up , .5 = an octave down)

kloop -- start loop point (in samples)

kend -- end loop point (in samples)

lposcil3 (looping precise oscillator) allows varying at k-rate, the
starting and ending point of a sample contained in a table (GEN01). This
can be useful when reading a sampled loop of a wavetable, where repeat
speed can be varied during the performance.


===========================================================================
lposcila                                                           *lposcila*

  Description

lposcila reads sampled sound from a table with looping and high precision.

  Syntax

ar lposcila aamp, kfreqratio, kloop, kend, ift [,iphs] 

  Initialization

ift -- function table number

iphs -- initial phase (in samples)

  Performance

ar -- output signal

aamp -- amplitude

kfreqratio -- multiply factor of table frequency (for example: 1 =
original frequency, 1.5 = a fifth up , .5 = an octave down)

kloop -- start loop point (in samples)

kend -- end loop point (in samples)

lposcila is the same as lposcil, but has an audio-rate amplitude
argument (instead of k-rate) to allow fast envelope transients.


===========================================================================
lposcilsa                                                         *lposcilsa*

  Description

lposcilsa reads stereo sampled sound from a table with looping and high
precision.

  Syntax

ar1, ar2 lposcilsa aamp, kfreqratio, kloop, kend, ift [,iphs] 

  Initialization

ift -- function table number

iphs -- initial phase (in samples)

  Performance

ar1, ar2 -- output signal

aamp -- amplitude

kfreqratio -- multiply factor of table frequency (for example: 1 =
original frequency, 1.5 = a fifth up , .5 = an octave down)

kloop -- start loop point (in samples)

kend -- end loop point (in samples)

lposcilsa is the same as lposcila, but works with stereo files loaded
with GEN01.


===========================================================================
lposcilsa2                                                       *lposcilsa2*

  Description

lposcilsa2 reads stereo sampled sound from a table with looping and high
precision.

  Syntax

ar1, ar2 lposcilsa2 aamp, kfreqratio, kloop, kend, ift [,iphs] 

  Initialization

ift -- function table number

iphs -- initial phase (in samples)

  Performance

ar1, ar2 -- output signal

aamp -- amplitude

kfreqratio -- multiply factor of table frequency (for example: 1 =
original frequency, 2 = an octave up). Only integers are allowed

kloop -- start loop point (in samples)

kend -- end loop point (in samples)

lposcilsa2 is the same as lposcilsa, but no interpolation is implemented
and only works with integer kfreqratio values. Much faster than
lposcilsa, it is mainly intended to be used with kfreqratio = 1, being
in this case a fast substitute of soundin, since the soundfile must be
entirely loaded in memory.


===========================================================================
lpread                                                               *lpread*

  Description

Reads a control file of time-ordered information frames.

  Syntax

krmsr, krmso, kerr, kcps lpread ktimpnt, ifilcod [, inpoles] [, ifrmrate]

  Initialization

ifilcod -- integer or character-string denoting a control-file
(reflection coefficients and four parameter values) derived from n-pole
linear predictive spectral analysis of a source audio signal. An integer
denotes the suffix of a file lp.m; a character-string (in double quotes)
gives a filename, optionally a full pathname. If not fullpath, the file
is sought first in the current directory, then in that of the
environment variable SADIR (if defined). Memory usage depends on the
size of the file, which is held entirely in memory during computation
but shared by multiple calls (see also adsyn, pvoc).

inpoles (optional, default=0) -- number of poles in the lpc analysis. It
is required only when the control file does not have a header; it is
ignored when a header is detected.

ifrmrate (optional, default=0) -- frame rate per second in the lpc
analysis. It is required only when the control file does not have a
header; it is ignored when a header is detected.

  Performance

lpread accesses a control file of time-ordered information frames, each
containing n-pole filter coefficients derived from linear predictive
analysis of a source signal at fixed time intervals (e.g. 1/100 of a
second), plus four parameter values:

krmsr -- root-mean-square (rms) of the residual of analysis

krmso -- rms of the original signal

kerr -- the normalized error signal

kcps -- pitch in Hz

ktimpnt -- The passage of time, in seconds, through the analysis file.
ktimpnt must always be positive, but can move forwards or backwards in
time, be stationary or discontinuous, as a pointer into the analysis file.

lpread gets its values from the control file according to the input
value ktimpnt (in seconds). If ktimpnt proceeds at the analysis rate,
time-normal synthesis will result; proceeding at a faster, slower, or
variable rate will result in time-warped synthesis. At each k-period,
lpread interpolates between adjacent frames to more accurately determine
the parameter values (presented as output) and the filter coefficient
settings (passed internally to a subsequent lpreson).

The error signal kerr (between 0 and 1) derived during predictive
analysis reflects the deterministic/random nature of the analyzed
source. This will emerge low for pitched (periodic) material and higher
for noisy material. The transition from voiced to unvoiced speech, for
example, produces an error signal value of about .3. During synthesis,
the error signal value can be used to determine the nature of the
lpreson driving function: for example, by arbitrating between pitched
and non-pitched input, or even by determining a mix of the two. In
normal speech resynthesis, the pitched input to lpreson is a wideband
periodic signal or pulse train derived from a unit such as buzz, and the
nonpitched source is usually derived from rand. However, any audio
signal can be used as the driving function, the only assumption of the
analysis being that it has a flat response.

lpfreson is a formant shifted lpreson, in which kfrqratio is the (cps)
ratio of shifted to original formant positions. This permits synthesis
in which the source object changes its apparent acoustic size. lpfreson
with kfrqratio = 1 is equivalent to lpreson.

Generally, lpreson provides a means whereby the time-varying content and
spectral shaping of a composite audio signal can be controlled by the
dynamic spectral content of another. There can be any number of
lpread/lpreson (or lpfreson) pairs in an instrument or in an orchestra;
they can read from the same or different control files independently.


===========================================================================
lpreson                                                             *lpreson*

  Description

Resynthesises a signal from the data passed internally by a previous
lpread.

  Syntax

ares lpreson asig

  Performance

asig -- an audio driving function for resynthesis.

lpreson receives values internally produced by a leading lpread.lpread
gets its values from the control file according to the input value
ktimpnt (in seconds). If ktimpnt proceeds at the analysis rate,
time-normal synthesis will result; proceeding at a faster, slower, or
variable rate will result in time-warped synthesis. At each k-period,
lpread interpolates between adjacent frames to more accurately determine
the parameter values (presented as output) and the filter coefficient
settings (passed internally to a subsequent lpreson).

The error signal kerr (between 0 and 1) derived during predictive
analysis reflects the deterministic/random nature of the analyzed
source. This will emerge low for pitched (periodic) material and higher
for noisy material. The transition from voiced to unvoiced speech, for
example, produces an error signal value of about .3. During synthesis,
the error signal value can be used to determine the nature of the
lpreson driving function: for example, by arbitrating between pitched
and non-pitched input, or even by determining a mix of the two. In
normal speech resynthesis, the pitched input to lpreson is a wideband
periodic signal or pulse train derived from a unit such as buzz, and the
nonpitched source is usually derived from rand. However, any audio
signal can be used as the driving function, the only assumption of the
analysis being that it has a flat response.

lpfreson is a formant shifted lpreson, in which kfrqratio is the (cps)
ratio of shifted to original formant positions. This permits synthesis
in which the source object changes its apparent acoustic size. lpfreson
with kfrqratio = 1 is equivalent to lpreson.

Generally, lpreson provides a means whereby the time-varying content and
spectral shaping of a composite audio signal can be controlled by the
dynamic spectral content of another. There can be any number of
lpread/lpreson (or lpfreson) pairs in an instrument or in an orchestra;
they can read from the same or different control files independently.


===========================================================================
lpshold                                                             *lpshold*

  Description

Generate control signal consisting of held segments delimited by two or
more specified points. The entire envelope is looped at kfreq rate. Each
parameter can be varied at k-rate.

  Syntax

ksig lpshold kfreq, ktrig, iphase, ktime0, kvalue0  [, kvalue1] [, ktime1] [, kvalue2] [, ktime2] [...]

  Performance

ksig -- Output signal

kfreq -- Repeat rate in Hz or fraction of Hz

ktrig -- If non-zero, retriggers the envelope from start (see trigger
opcode), before the envelope cycle is completed.

iphase -- A vaue between 0 and 1 to say where to start the loop. Zero,
the commonest value, indicates the beginning.

kvalue0...kvalueN -- Values of points

ktime0...ktimeN -- Times between points; expressed in fractions of a
cycle (see below). The final time designates a ramp between the final
value and the first value.

lpshold is similar to loopseg, but can generate only horizontal
segments, i.e. holds values for each time interval placed between ktimeN
and ktimeN+1. It can be useful, among other things, for melodic control,
like old analog sequencers.


===========================================================================
lpsholdp                                                           *lpsholdp*

  Description

Generate control signal consisiting of held segments delimited by two or
more specified points. The entire envelope can be looped at time-variant
rate. Each segment coordinate can also be varied at k-rate.

  Syntax

ksig lpsholdp  kphase, kvalue0, ktime0  [, kvalue1] [, ktime1] \
      [, kvalue2] [, ktime2] [...]

  Performance

ksig - output signal

kphase -- point of the sequence read, expressed as a fraction of a cycle
(0 to 1)

kvalue0...kvalueN -- Values of points

ktime0...ktimeN -- Times between points; expressed in fractions of a
cycle (see below). The final time designates a ramp between the final
value and the first value.

lpsholdp opcode is similar to lpshold; the only difference is that,
instead of frequency, a time-variant phase is required. If you use a
phasor to get the phase value, you will have a behaviour identical to
lpshold, but interesting results can be achieved when using phases
having non-linear motions, making lpsholdp more powerful and general
than lpshold.


===========================================================================
lpslot                                                               *lpslot*

  Description

Selects the slot to be use by further lp opcodes.

  Syntax

lpslot islot

  Initialization

islot -- number of slot to be selected.

  Performance

lpslot selects the slot to be use by further lp opcodes. This is the way
to load and reference several analyses at the same time.


===========================================================================
lua_exec                                                           *lua_exec*

  Description

Executes an arbitrary block of Lua code from the Csound orchestra. The
code is executed at initialization time, typically from the orchestra
header.

  Syntax

lua_exec Sluacode

  Initialization

Sluacode -- A block of Lua code, of any length. Multi-line blocks may be
enclosed in double braces (i.e. |{{ }}|). This code is evaluated once at
initialization time, typically from the orchestra header. Global and
local variables, functions, tables, and classes may be declared and
defined. Objects defined at global Lua scope remain in scope throughout
the performance, and are visible to any other Lua code in the same
Csound thread.

The running instance of Csound is stored as a Lua lightuserdata in a
global variable |csound|. This can be passed to any Csound API function.
One use of this would be to generate a score using Lua in the orchestra
header, and schedule the events for performance using |csoundInputMessage|.

  Note

By default, all objects defined in Lua are defined at global scope. In
order to ensure that objects are confined to their own block of code,
that is to ensure that the object is visible only in lexical scope, the
object must be declared as local. This is the feature of Lua that
beginners tend to find the most troublesome.

Another thing to look out for is that Lua arrays use 1-based indexing,
not the 0-based indexing used in C and many other programming languages.


===========================================================================
lua_opdef                                                         *lua_opdef*

  Description

Define an opcode in Lua at i-rate. The opcode can take any number of
output and/or input arguments of any type. The code is executed at
initialization time, typically from the orchestra header. Global and
local variables, functions, tables, and classes may be declared and
defined. Objects defined at global Lua scope remain in scope throughout
the performance, and are visible to any other Lua code in the same
Csound thread.

  Note

By default, all objects defined in Lua are defined at global scope. In
order to ensure that objects are confined to their own block of code,
that is to ensure that the object is visible only in lexical scope, the
object must be declared as local. This is the feature of Lua that
beginners tend to find the most troublesome.

Another thing to look out for is that Lua arrays use 1-based indexing,
not the 0-based indexing used in C and many other programming languages.

  Syntax

lua_opdef Sname, Sluacode

  Initialization

Sname -- The name of the opcode.

Sluacode -- A block of Lua code, of any length. Multi-line blocks may be
enclosed in double braces (i.e. |{{ }}|). This code is evaluated once at
initialization time.

The Lua code must define all functions that will be called from Csound,
using the following naming convention, where opcodename stands for the
actual opcode name:

  * |opcodename_init| for the i-rate opcode subroutine.
  * |opcodename_kontrol| for the k-rate opcode subroutine.
  * |opcodename_audio| for the a-rate opcode subroutine.
  * |opcodename_noteoff| for the note-off subroutine. 

Each of these Lua functions will receive three lightuserdata (i.e.
pointer) arguments: the CSOUND object, the opcode instance, and a
pointer to the opcode arguments, which the Lua code must be type cast to
a LuaJIT FFI ctype structure containing the opcode output arguments,
input arguments, and state variables. Using LuaJIT FFI, the elements of
this structure will be accessible as though they were Lua types.

Each of these Lua functions must return 0 for success or 1 for failure.

The Lua functions may do absolutely anything, although of course if
real-time performance is expected, care must be taken to disable Lua
garbage collection and observe other recommendations for real-time code.


===========================================================================
lua_opcall                                                       *lua_opcall*

  Syntax

lua_iopcall Sname, ...

lua_ikopcall Sname, ...

lua_iaopcall Sname, ...

lua_iopcall_off Sname, ...

lua_ikopcall_off Sname, ...

lua_iaopcall_off Sname, ...

  Initialization and Performance

Sname -- The name of the opcode.

... -- An arbitrary list of any number of output and input arguments, of
any type. The number, sequence, and types of these arguments must agree
with the cdef of the arguments structure that is declared in the
corresponding |lua_opdef| opcode.

|lua_iopcall| calls a Lua opcode at i-rate only. Requires |opname_init|
to be defined in Lua.

|lua_ikopcall| calls a Lua opcode at i-rate and k-rate. Requires
|opname_init| and |opname_kontrol| to be defined in Lua.

|lua_iaopcall| calls a Lua opcode at i-rate and a-rate. Requires
|opname_init| and |opname_audio| to be defined in Lua.

|lua_iopcall_off| calls a Lua opcode at i-rate only. Requires
|opname_init| and |opname_noteoff| to be defined in Lua.

|lua_ikopcall_off| calls a Lua opcode at i-rate and k-rate. Requires
|opname_init|, |opname_kontrol|, and |opname_noteoff| to be defined in Lua.

|lua_iaopcall_off| calls a Lua opcode at i-rate and a-rate. Requires
|opname_init|, |opname_audio|, and |opname_noteoff| to be defined in Lua.

Lua code accesses elements of arguments as follows (pointers to both
scalars and arrays are dereferenced by the Lua array access operator):

            ffi.cdef(' struct arguments_t { double *a_out, double *i_in, double *i_txt, double *f_sig };');
            local arguments = ffi.cast("struct arguments_t *", carguments_lightuserdata)
            for i = 0, ksmps -1 do begin carguments.a_out[i] = carguments.i_in[0] * 3 end end

The "off" variants of the opcode always schedule a "note off" event that
is called when the intrument instance is removed from the active list,
and which can be used to release unneeded resources, reschedule the
instrument to render a reverb tail, and so on.


===========================================================================
mac                                                                     *mac*

  Description

Multiplies and accumulates a- and k-rate signals.

  Syntax

ares mac ksig1, asig1 [, ksig2] [, asig2] [, ksig3] [, asig3] [...]

  Performance

ksig1, etc. -- k-rate input signals

asig1, etc. -- a-rate input signals

mac multiplies and accumulates a- and k-rate signals. It is equivalent to:

        ares = asig1*ksig1 + asig2*ksig2 + asig3*ksig3 + ...


===========================================================================
maca                                                                   *maca*

  Description

Multiply and accumulate a-rate signals only.

  Syntax

ares maca asig1 , asig2 [, asig3] [, asig4] [, asig5] [...]

  Performance

asig1, asig2, ... -- a-rate input signals

maca multiplies and accumulates a-rate signals only. It is equivalent to:

        ares = asig1*asig2 + asig3*asig4 + asig5*asig6 + ...


===========================================================================
madsr                                                                 *madsr*

  Description

Calculates the classical ADSR envelope using the linsegr mechanism.

  Syntax

ares madsr iatt, idec, islev, irel [, idel] [, ireltim]

kres madsr iatt, idec, islev, irel [, idel] [, ireltim]

  Initialization

iatt -- duration of attack phase

idec -- duration of decay

islev -- level for sustain phase

irel -- duration of release phase.

idel -- period of zero before the envelope starts

ireltim (optional, default=-1) -- Control release time after receiving a
MIDI noteoff event. If less than zero, the longest release time given in
the current instrument is used. If zero or more, the given value will be
used for release time. Its default value is -1. (New in Csound 3.59 -
not yet properly tested)

Please note that the release time cannot be longer than 32767/kr seconds.

  Performance

The envelope is in the range 0 to 1 and may need to be scaled further.
The envelope may be described as:

Picture of an ADSR envelope.

Picture of an ADSR envelope.

The length of the sustain is calculated from the length of the note.
This means adsr is not suitable for use with MIDI events. The opcode
madsr uses the linsegr mechanism, and so can be used in MIDI applications.

You can use other pre-made envelopes which start a release segment upon
receiving a note off message, like linsegr and expsegr, or you can
construct more complex envelopes using xtratim and release. Note that
you don't need to use xtratim if you are using madsr, since the time is
extended automatically.

  Note

Times for iatt, idec and irel cannot be 0. If 0 is used, no envelope is
generated. Use a very small value like 0.0001 if you need an
instantaneous attack, decay or release.


===========================================================================
mags                                                                   *mags*

  Description

This opcode returns the magnitudes of a complex-number array (in rfft
format), as a real-valued array with half the size of its input plus
one. The magnitude for the Nyquist frequency are kept in the last
position of the array.

  Syntax

kout[] mags kin[]

  Performance

kout[] -- output array containing the magnitudes (size = input_size/2 +
1). It will be created if it does not exist.

kin[] -- input array containing the complex-valued real-imaginary input.


===========================================================================
mandel                                                               *mandel*

  Description

Returns the number of iterations corresponding to a given point of
complex plane by applying the Mandelbrot set formula.

  Syntax

kiter, koutrig mandel  ktrig, kx, ky, kmaxIter

  Performance

kiter - number of iterations

koutrig - output trigger signal

ktrig - input trigger signal

kx, ky - coordinates of a given point belonging to the complex plane

kmaxIter - maximum iterations allowed

mandel is an opcode that allows the use of the Mandelbrot set formula to
generate an output that can be applied to any musical (or non-musical)
parameter. It has two output arguments: kiter, that contains the
iteration number of a given point, and koutrig, that generates a trigger
'bang' each time kiter changes. A new number of iterations is evaluated
only when ktrig is set to a non-zero value. The coordinates of the
complex plane are set in kx and ky, while kmaxIter contains the maximum
number of iterations. Output values, which are integer numbers, can be
mapped in any sorts of ways by the composer.


===========================================================================
mandol                                                               *mandol*

  Description

An emulation of a mandolin.

  Syntax

ares mandol kamp, kfreq, kpluck, kdetune, kgain, ksize \
    [, ifn] [, iminfreq]

  Initialization

ifn -- table number containing the pluck wave form. The file
mandpluk.aiff is suitable for this. It is also available at
ftp://ftp.cs.bath.ac.uk/pub/dream/documentation/sounds/modelling/.

iminfreq (optional, default=0) -- Lowest frequency to be played on the
note. If it is omitted it is taken to be the same as the initial kfreq.

  Performance

kamp -- Amplitude of note.

kfreq -- Frequency of note played.

kpluck -- The pluck position, in range 0 to 1. Suggest 0.4.

kdetune -- The proportional detuning between the two strings. Suggested
range 0.9 to 1.

kgain -- the loop gain of the model, in the range 0.97 to 1.

ksize -- The size of the body of the mandolin. Range 0 to 2.


===========================================================================
maparray                                                           *maparray*

  Description

Apply a function of one argument to every element of a vector
(one-dimensional k-rate array).

  Syntax

karray maparray kinarray, String

karray maparray_i kinarray, String

  Initialization

String -- a string that names an opcode function, at i-rate for
maparray_i or k-rate for maparray.

  Performance

karray -- array for answers.

kinarray -- array for arguments to the function.


===========================================================================
marimba                                                             *marimba*

  Description

Audio output is a tone related to the striking of a wooden block as
found in a marimba. The method is a physical model developed from Perry
Cook but re-coded for Csound.

  Syntax

ares marimba kamp, kfreq, ihrd, ipos, imp, kvibf, kvamp, ivibfn, idec \
      [, idoubles] [, itriples]

  Initialization

ihrd -- the hardness of the stick used in the strike. A range of 0 to 1
is used. 0.5 is a suitable value.

ipos -- where the block is hit, in the range 0 to 1.

imp -- a table of the strike impulses. The file marmstk1.wav is a
suitable function from measurements and can be loaded with a GEN01
table. It is also available at
ftp://ftp.cs.bath.ac.uk/pub/dream/documentation/sounds/modelling/.

ivfn -- shape of vibrato, usually a sine table, created by a function

idec -- time before end of note when damping is introduced

idoubles (optional) -- percentage of double strikes. Default is 40%.

itriples (optional) -- percentage of triple strikes. Default is 20%.

  Performance

kamp -- Amplitude of note.

kfreq -- Frequency of note played.

kvibf -- frequency of vibrato in Hertz. Suggested range is 0 to 12

kvamp -- amplitude of the vibrato


===========================================================================
massign                                                             *massign*

  Description

Assigns a MIDI channel number to a Csound instrument.

  Syntax

massign ichnl, insnum[, ireset]

massign ichnl, "insname"[, ireset]

  Initialization

ichnl -- MIDI channel number (1-16).

insnum -- Csound orchestra instrument number. If zero or negative, the
channel is muted (i.e. it doesn't trigger a csound instrument, though
information will still be received by opcodes like midiin).

“insname” -- A string (in double-quotes) representing a named instrument.

ireset -- If non-zero resets the controllers; default is to reset.

  Performance

Assigns a MIDI channel number to a Csound instrument. Also useful to
make sure a certain instrument (if its number is from 1 to 16) will not
be triggered by midi noteon messages (if using something midiin to
interpret midi information). In this case set insnum to 0 or a negative
number.

If ichan is set to 0, the value of insnum is used for all channels. This
way you can route all MIDI channels to a single Csound instrument. You
can also disable triggering of instruments from MIDI note events from
all channels with the following line:

massign 0,0

This can be useful if you are doing all MIDI evaluation within Csound
with an always on instrument(e.g. using midiin and turnon) to avoid
doubling the instrument when a note is played.


===========================================================================
max                                                                     *max*

  Description

The max opcode takes any number of a-rate, k-rate or i-rate signals as
input (all of the same rate), and outputs a signal at the same rate that
is the maximum of all of the inputs. For a-rate signals, the inputs are
compared one sample at a time (i.e. max does not scan an entire ksmps
period of a signal for its local maximum as the max_k opcode does).

  Syntax

amax max ain1, ain2 [, ain3] [, ain4] [...]

kmax max kin1, kin2 [, kin3] [, kin4] [...]

imax max iin1, iin2 [, iin3] [, iin4] [...]

  Performance

ain1, ain2, ... -- a-rate signals to be compared.

kin1, kin2, ... -- k-rate signals to be compared.

iin1, iin2, ... -- i-rate signals to be compared.


===========================================================================
maxabs                                                               *maxabs*

  Description

The maxabs opcode takes any number of a-rate or k-rate signals as input
(all of the same rate), and outputs a signal at the same rate that is
the maximum of all of the inputs. It is identical to the max opcode
except that it takes the absolute value of each input before comparing
them. Therefore, the output is always non-negative. For a-rate signals,
the inputs are compared one sample at a time (i.e. maxabs does not scan
an entire ksmps period of a signal for its local maximum as the max_k
opcode does).

  Syntax

amax maxabs ain1, ain2 [, ain3] [, ain4] [...]

kmax maxabs kin1, kin2 [, kin3] [, kin4] [...]

  Performance

ain1, ain2, ... -- a-rate signals to be compared.

kin1, kin2, ... -- k-rate signals to be compared.


===========================================================================
maxabsaccum                                                     *maxabsaccum*

  Description

maxabsaccum compares two audio-rate variables and stores the maximum of
their absolute values into the first.

  Syntax

maxabsaccum aAccumulator, aInput

  Performance

aAccumulator -- audio variable to store the maximum value

aInput -- signal that aAccumulator is compared to

The maxabsaccum opcode is designed to accumulate the maximum value from
among many audio signals that may be in different note instances,
different channels, or otherwise cannot all be compared at once using
the maxabs opcode. maxabsaccum is identical to maxaccum except that it
takes the absolute value of aInput before the comparison. Its semantics
are similar to vincr since aAccumulator is used as both an input and an
output variable, except that maxabsaccum keeps the maximum absolute
value instead of adding the signals together. maxabsaccum performs the
following operation on each pair of samples:

            if  (abs(aInput) > aAccumulator)  aAccumulator = abs(aInput)

aAccumulator will usually be a global audio variable. At the end of any
given computation cycle (k-period), after its value is read and used in
some way, the accumulator variable should usually be reset to zero
(perhaps by using the clear opcode). Clearing to zero is sufficient for
maxabsaccum, unlike the maxaccum opcode.


===========================================================================
maxaccum                                                           *maxaccum*

  Description

maxaccum compares two audio-rate variables and stores the maximum value
between them into the first.

  Syntax

maxaccum aAccumulator, aInput

  Performance

aAccumulator -- audio variable to store the maximum value

aInput -- signal that aAccumulator is compared to

The maxaccum opcode is designed to accumulate the maximum value from
among many audio signals that may be in different note instances,
different channels, or otherwise cannot all be compared at once using
the max opcode. Its semantics are similar to vincr since aAccumulator is
used as both an input and an output variable, except that maxaccum keeps
the maximum value instead of adding the signals together. maxaccum
performs the following operation on each pair of samples:

            if  (aInput > aAccumulator)  aAccumulator = aInput

aAccumulator will usually be a global audio variable. At the end of any
given computation cycle (k-period), after its value is read and used in
some way, the accumulator variable should usually be reset to zero
(perhaps by using the clear opcode). Care must be taken however if
aInput is negative at any point, in which case the accumulator should be
initialized and reset to some large enough negative value that will
always be less than the input signals to which it is compared.


===========================================================================
maxalloc                                                           *maxalloc*

  Description

Limits the number of allocations of an instrument.

  Syntax

maxalloc insnum, icount

maxalloc Sinsname, icount

  Initialization

insnum -- instrument number

Sinsname -- instrument name

icount -- number of instrument allocations

  Performance

maxalloc limits the number of simultaneous instances (notes) of an
instrument. Any score events after the maximum has been reached, are
ignored.

All instances of maxalloc must be defined in the header section, not in
the instrument body.


===========================================================================
max_k                                                                 *max_k*

  Description

max_k outputs the local maximum (or minimum) value of the incoming asig
signal, checked in the time interval between ktrig has become true twice.

  Syntax

knumkout max_k asig, ktrig, itype

  Initialization

itype - itype determinates the behaviour of max_k (see below)

  Performance

asig - incoming (input) signal

ktrig - trigger signal

max_k outputs the local maximum (or minimum) value of the incoming asig
signal, checked in the time interval between ktrig has become true
twice. itype determinates the behaviour of max_k:

1 - absolute maximum (sign of negative values is changed to positive
before evaluation).

2 - actual maximum.

3 - actual minimum.

4 - calculate average value of asig in the time interval since the last
trigger.

This opcode can be useful in several situations, for example to
implement a vu-meter.


===========================================================================
maxarray                                                           *maxarray*

  Description

The maxarray opcode returns the maximum value in a k-rate array, and
optional its index.

  Syntax

kmax [,kindx] maxarray karray

  Performance

kmax -- variable for result.

kindx -- position (index) of result in array.

karray -- array for reading.


===========================================================================
mclock                                                               *mclock*

  Description

Sends a MIDI CLOCK message.

  Syntax

mclock ifreq

  Initialization

ifreq -- clock message frequency rate in Hz

  Performance

Sends a MIDI CLOCK message (0xF8) every 1/ifreq seconds. So ifreq is the
frequency rate of CLOCK message in Hz.


===========================================================================
mdelay                                                               *mdelay*

  Description

A MIDI delay opcode.

  Syntax

mdelay kstatus, kchan, kd1, kd2, kdelay

  Performance

kstatus -- status byte of MIDI message to be delayed

kchan -- MIDI channel (1-16)

kd1 -- first MIDI data byte

kd2 -- second MIDI data byte

kdelay -- delay time in seconds

Each time that kstatus is other than zero, mdelay outputs a MIDI message
to the MIDI out port after kdelay seconds. This opcode is useful in
implementing MIDI delays. Several instances of mdelay can be present in
the same instrument with different argument values, so complex and
colorful MIDI echoes can be implemented. Further, the delay time can be
changed at k-rate.


===========================================================================
median                                                               *median*

  Description

Implementation of a median filter.

  Syntax

ares median asig, ksize, imaxsize [, iskip]

  Initialization

imaxsize -- the maximun size of the window used to select the data.

iskip -- initial disposition of internal data space. A zero value will
clear the space; a non-zero value will allow previous information to
remain. The default value is 0.

  Performance

asig -- input signal to be filtered

ksize -- size of the window over which the input is to be filtered. It
must not exceed the maximum window size; if it does it is truncated.

median is a simple filter that retuns the median value of the last ksize
values. It has a lowpass action. The efficiency decreases as the window
size increases.


===========================================================================
mediank                                                             *mediank*

  Description

Implementation of a median filter.

  Syntax

kres mediank kin, ksize, imaxsize [, iskip]

  Initialization

imaxsize -- the maximun size of the window used to select the data.

iskip -- initial disposition of internal data space. A zero value will
clear the space; a non-zero value will allow previous information to
remain. The default value is 0.

  Performance

kin -- krate value to be filtered

ksize -- size of the window over which the input is to be filtered. It
must not exceed the maximum window size; if it does it is truncated.

mediank is a simple filter that retuns the median value of the last
ksize values. It has a lowpass action. The efficiency decreases as the
window size increases.


===========================================================================
metro                                                                 *metro*

  Description

Generate a metronomic signal to be used in any circumstance an
isochronous trigger is needed.

  Syntax

ktrig  metro  kfreq [, initphase]

  Initialization

initphase - initial phase value (in the 0 to 1 range)

  Performance

ktrig - output trigger signal

kfreq - frequency of trigger bangs in cps

metro is a simple opcode that outputs a sequence of isochronous bangs
(that is 1 values) each 1/kfreq seconds. Trigger signals can be used in
any circumstance, mainly to temporize realtime algorithmic compositional
structures.

  Note

metro will produce a trigger signal of 1 when its phase is exactly 0 or
1. If you want to skip the initial trigger, use a very small value like
0.00000001.


===========================================================================
midglobal                                                         *midglobal*

  Description

With the midremot and midglobal opcodes you are able to perform
instruments on remote machines and control them from a master machine.
The remote opcodes are implemented using the master/client model. All
the machines involved contain the same orchestra but only the master
machine contains the information of the midi score. During the
performance the master machine sends the midi events to the clients. The
midglobal opcode sends the events to all the machines involved in the
remote concert. These machines are determined by the midremot
definitions made above the midglobal command. To send events to only one
machine use midremot.

  Syntax

midglobal isource, instrnum [,instrnum...] 

  Initialization

isource -- a string that is the intended host computer (e.g.
192.168.0.100). This is the source host which generates the events of
the given instrument(s) and sends it to all the machines involved in the
remote concert.

instrnum -- a list of instrument numbers which will be played on the
destination machines


===========================================================================
midic14                                                             *midic14*

  Description

Allows a floating-point 14-bit MIDI signal scaled with a minimum and a
maximum range.

  Syntax

idest midic14 ictlno1, ictlno2, imin, imax [, ifn]

kdest midic14 ictlno1, ictlno2, kmin, kmax [, ifn]

  Initialization

idest -- output signal

ictln1o -- most-significant byte controller number (0-127)

ictlno2 -- least-significant byte controller number (0-127)

imin -- user-defined minimum floating-point value of output

imax -- user-defined maximum floating-point value of output

ifn (optional) -- table to be read when indexing is required. Table must
be normalized. Output is scaled according to imin and imax values.

  Performance

kdest -- output signal

kmin -- user-defined minimum floating-point value of output

kmax -- user-defined maximum floating-point value of output

midic14 (i- and k-rate 14 bit MIDI control) allows a floating-point
14-bit MIDI signal scaled with a minimum and a maximum range. The
minimum and maximum values can be varied at k-rate. It can use optional
interpolated table indexing. It requires two MIDI controllers as input.

  Note

Please note that the midic family of opcodes are designed for MIDI
triggered events, and don't require a channel number since they will
respond to the same channel as the one that triggered the instrument
(see massign). However they will crash if called from a score driven event.


===========================================================================
midic21                                                             *midic21*

  Description

Allows a floating-point 21-bit MIDI signal scaled with a minimum and a
maximum range.

  Syntax

idest midic21 ictlno1, ictlno2, ictlno3, imin, imax [, ifn]

kdest midic21 ictlno1, ictlno2, ictlno3, kmin, kmax [, ifn]

  Initialization

idest -- output signal

ictln1o -- most-significant byte controller number (0-127)

ictlno2 -- mid-significant byte controller number (0-127)

ictlno3 -- least-significant byte controller number (0-127)

imin -- user-defined minimum floating-point value of output

imax -- user-defined maximum floating-point value of output

ifn (optional) -- table to be read when indexing is required. Table must
be normalized. Output is scaled according to the imin and imax values.

  Performance

kdest -- output signal

kmin -- user-defined minimum floating-point value of output

kmax -- user-defined maximum floating-point value of output

midic21 (i- and k-rate 21 bit MIDI control) allows a floating-point
21-bit MIDI signal scaled with a minimum and a maximum range. Minimum
and maximum values can be varied at k-rate. It can use optional
interpolated table indexing. It requires three MIDI controllers as input.

  Note

Please note that the midic family of opcodes are designed for MIDI
triggered events, and don't require a channel number since they will
respond to the same channel as the one that triggered the instrument
(see massign). However they will crash if called from a score driven event.


===========================================================================
midic7                                                               *midic7*

  Description

Allows a floating-point 7-bit MIDI signal scaled with a minimum and a
maximum range.

  Syntax

idest midic7 ictlno, imin, imax [, ifn]

kdest midic7 ictlno, kmin, kmax [, ifn]

  Initialization

idest -- output signal

ictlno -- MIDI controller number (0-127)

imin -- user-defined minimum floating-point value of output

imax -- user-defined maximum floating-point value of output

ifn (optional) -- table to be read when indexing is required. Table must
be normalized. Output is scaled according to the imin and imax values.

  Performance

kdest -- output signal

kmin -- user-defined minimum floating-point value of output

kmax -- user-defined maximum floating-point value of output

midic7 (i- and k-rate 7 bit MIDI control) allows a floating-point 7-bit
MIDI signal scaled with a minimum and a maximum range. It also allows
optional non-interpolated table indexing. In midic7 minimum and maximum
values can be varied at k-rate.

  Note

Please note that the midic family of opcodes are designed for MIDI
triggered events, and don't require a channel number since they will
respond to the same channel as the one that triggered the instrument
(see massign). However they will crash if called from a score driven event.


===========================================================================
midichannelaftertouch                                 *midichannelaftertouch*

  Description

midichannelaftertouch is designed to simplify writing instruments that
can be used interchangeably for either score or MIDI input, and to make
it easier to adapt instruments originally written for score input to
work with MIDI input.

In general, it should be possible to write instrument definitions that
work identically with both scores and MIDI, including both MIDI files
and real-time MIDI input, without using any conditional statements, and
that take full advantage of MIDI voice messages.

Note that correlating Csound instruments with MIDI channel numbers is
done using the massign opcode for real-time performance,. For
file-driven performance, instrument numbers default to MIDI channel
number + 1, but the defaults are overridden by any MIDI program change
messages in the file.

  Syntax

midichannelaftertouch xchannelaftertouch [, ilow] [, ihigh]

  Initialization

ilow (optional) -- optional low value after rescaling, defaults to 0.

ihigh (optional) -- optional high value after rescaling, defaults to 127.

  Performance

xchannelaftertouch -- returns the MIDI channel aftertouch during MIDI
activation, remains unchanged otherwise.

If the instrument was activated by MIDI input, the opcode overwrites the
value of xchannelaftertouch with the corresponding value from MIDI
input. If the instrument was NOT activated by MIDI input, the value of
xchannelaftertouch remains unchanged.

This enables score p-fields to receive MIDI input data during MIDI
activation, and score values otherwise.

  Adapting a score-activated Csound instrument.

See the MIDI interop opcodes section for details on adapting score
driven instruments for MIDI or vice-versa.


===========================================================================
midichn                                                             *midichn*

  Description

midichn returns the MIDI channel number (1 - 16) from which the note was
activated. In the case of score notes, it returns 0.

  Syntax

ichn midichn

  Initialization

ichn -- channel number. If the current note was activated from score, it
is set to zero.


===========================================================================
midicontrolchange                                         *midicontrolchange*

  Description

midicontrolchange is designed to simplify writing instruments that can
be used interchangeably for either score or MIDI input, and to make it
easier to adapt instruments originally written for score input to work
with MIDI input.

In general, it should be possible to write instrument definitions that
work identically with both scores and MIDI, including both MIDI files
and real-time MIDI input, without using any conditional statements, and
that take full advantage of MIDI voice messages.

Note that correlating Csound instruments with MIDI channel numbers is
done using the massign opcode for real-time performance,. For
file-driven performance, instrument numbers default to MIDI channel
number + 1, but the defaults are overridden by any MIDI program change
messages in the file.

  Syntax

midicontrolchange xcontroller, xcontrollervalue [, ilow] [, ihigh]

  Initialization

ilow (optional) -- optional low value after rescaling, defaults to 0.

ihigh (optional) -- optional high value after rescaling, defaults to 127.

  Performance

xcontroller -- specifies a MIDI controller number (0-127).

xcontrollervalue -- returns the value of the MIDI controller during MIDI
activation, remains unchanged otherwise.

If the instrument was activated by MIDI input, the opcode overwrites the
values of the xcontroller and xcontrollervalue with the corresponding
values from MIDI input. If the instrument was NOT activated by MIDI
input, the values of xcontroller and xcontrollervalue remain unchanged.

This enables score p-fields to receive MIDI input data during MIDI
activation, and score values otherwise.

  Adapting a score-activated Csound instrument.

See the MIDI interop opcodes section for details on adapting score
driven instruments for MIDI or vice-versa.


===========================================================================
midictrl                                                           *midictrl*

  Description

Get the current value (0-127) of a specified MIDI controller.

  Syntax

ival midictrl inum [, imin] [, imax]

kval midictrl inum [, imin] [, imax]

  Initialization

inum -- MIDI controller number (0-127)

imin, imax -- set minimum and maximum limits on values obtained.

  Performance

Get the current value (0-127) of a specified MIDI controller.

Warning

midictrl should only be used in notes that were triggered from MIDI, so
that an associated channel number is available. For notes activated from
the score, line events, or orchestra, the ctrl7 opcode that takes an
explicit channel number should be used instead.


===========================================================================
mididefault                                                     *mididefault*

  Description

mididefault is designed to simplify writing instruments that can be used
interchangeably for either score or MIDI input, and to make it easier to
adapt instruments originally written for score input to work with MIDI
input.

In general, it should be possible to write instrument definitions that
work identically with both scores and MIDI, including both MIDI files
and real-time MIDI input, without using any conditional statements, and
that take full advantage of MIDI voice messages.

Note that correlating Csound instruments with MIDI channel numbers is
done using the massign opcode for real-time performance,. For
file-driven performance, instrument numbers default to MIDI channel
number + 1, but the defaults are overridden by any MIDI program change
messages in the file.

  Syntax

mididefault xdefault, xvalue

  Performance

xdefault -- specifies a default value that will be used during MIDI
activation.

xvalue -- overwritten by xdefault during MIDI activation, remains
unchanged otherwise.

If the instrument was activated by MIDI input, the opcode will overwrite
the value of xvalue with the value of xdefault. If the instrument was
NOT activated by MIDI input, xvalue will remain unchanged.

This enables score pfields to receive a default value during MIDI
activation, and score values otherwise.

  Adapting a score-activated Csound instrument.

See the MIDI interop opcodes section for details on adapting score
driven instruments for MIDI or vice-versa.


===========================================================================
midiin                                                               *midiin*

  Description

Returns a generic MIDI message received by the MIDI IN port

  Syntax

kstatus, kchan, kdata1, kdata2 midiin

  Performance

kstatus -- the type of MIDI message. Can be:

  * 128 (note off)

  * 144 (note on)

  * 160 (polyphonic aftertouch)

  * 176 (control change)

  * 192 (program change)

  * 208 (channel aftertouch)

  * 224 (pitch bend

  * 0 if no MIDI message are pending in the MIDI IN buffer

kchan -- MIDI channel (1-16)

kdata1, kdata2 -- message-dependent data values

midiin has no input arguments, because it reads at the MIDI in port
implicitly. It works at k-rate. Normally (i.e., when no messages are
pending) kstatus is zero, only when MIDI data are present in the MIDI IN
buffer, is kstatus set to the type of the relevant messages.

  Note

Be careful when using midiin in low numbered instruments, since a MIDI
note will launch additional instances of the instrument, resulting in
duplicate events and weird behaviour. Use massign to direct MIDI note on
messages to a different instrument or to disable triggering of
instruments from MIDI.


===========================================================================
midifilestatus                                               *midifilestatus*

  Description

Returns the current playback status at k-rate, of the input MIDI file, 1
if file is playing, 0 if the end-of-the file has been reached.

  Syntax

ksig  midifilestatus


===========================================================================
midinoteoff                                                     *midinoteoff*

  Description

midinoteoff is designed to simplify writing instruments that can be used
interchangeably for either score or MIDI input, and to make it easier to
adapt instruments originally written for score input to work with MIDI
input.

In general, it should be possible to write instrument definitions that
work identically with both scores and MIDI, including both MIDI files
and real-time MIDI input, without using any conditional statements, and
that take full advantage of MIDI voice messages.

Note that correlating Csound instruments with MIDI channel numbers is
done using the massign opcode for real-time performance,. For
file-driven performance, instrument numbers default to MIDI channel
number + 1, but the defaults are overridden by any MIDI program change
messages in the file.

  Syntax

midinoteoff xkey, xvelocity

  Performance

xkey -- returns MIDI key during MIDI activation, remains unchanged
otherwise.

xvelocity -- returns MIDI velocity during MIDI activation, remains
unchanged otherwise.

If the instrument was activated by MIDI input, the opcode overwrites the
values of the xkey and xvelocity with the corresponding values from MIDI
input. If the instrument was NOT activated by MIDI input, the values of
xkey and xvelocity remain unchanged.

This enables score p-fields to receive MIDI input data during MIDI
activation, and score values otherwise.

  Adapting a score-activated Csound instrument.

See the MIDI interop opcodes section for details on adapting score
driven instruments for MIDI or vice-versa.


===========================================================================
midinoteoncps                                                 *midinoteoncps*

  Description

midinoteoncps is designed to simplify writing instruments that can be
used interchangeably for either score or MIDI input, and to make it
easier to adapt instruments originally written for score input to work
with MIDI input.

In general, it should be possible to write instrument definitions that
work identically with both scores and MIDI, including both MIDI files
and real-time MIDI input, without using any conditional statements, and
that take full advantage of MIDI voice messages.

Note that correlating Csound instruments with MIDI channel numbers is
done using the massign opcode for real-time performance,. For
file-driven performance, instrument numbers default to MIDI channel
number + 1, but the defaults are overridden by any MIDI program change
messages in the file.

  Syntax

midinoteoncps xcps, xvelocity

  Performance

xcps -- returns MIDI key translated to cycles per second during MIDI
activation, remains unchanged otherwise.

xvelocity -- returns MIDI velocity during MIDI activation, remains
unchanged otherwise.

If the instrument was activated by MIDI input, the opcode overwrites the
values of xcps and xvelocity with the corresponding values from MIDI
input. If the instrument was NOT activated by MIDI input, the values of
xcps and xvelocity remain unchanged.

This enables score p-fields to receive MIDI input data during MIDI
activation, and score values otherwise.

  Adapting a score-activated Csound instrument.

See the MIDI interop opcodes section for details on adapting score
driven instruments for MIDI or vice-versa.


===========================================================================
midinoteonkey                                                 *midinoteonkey*

  Description

midinoteonkey is designed to simplify writing instruments that can be
used interchangeably for either score or MIDI input, and to make it
easier to adapt instruments originally written for score input to work
with MIDI input.

In general, it should be possible to write instrument definitions that
work identically with both scores and MIDI, including both MIDI files
and real-time MIDI input, without using any conditional statements, and
that take full advantage of MIDI voice messages.

Note that correlating Csound instruments with MIDI channel numbers is
done using the massign opcode for real-time performance,. For
file-driven performance, instrument numbers default to MIDI channel
number + 1, but the defaults are overridden by any MIDI program change
messages in the file.

  Syntax

midinoteonkey xkey, xvelocity

  Performance

xkey -- returns MIDI key during MIDI activation, remains unchanged
otherwise.

xvelocity -- returns MIDI velocity during MIDI activation, remains
unchanged otherwise.

If the instrument was activated by MIDI input, the opcode overwrites the
values of xkey and xvelocity with the corresponding values from MIDI
input. If the instrument was NOT activated by MIDI input, the values of
xkey and xvelocity remain unchanged.

This enables score p-fields to receive MIDI input data during MIDI
activation, and score values otherwise.

  Adapting a score-activated Csound instrument.

See the MIDI interop opcodes section for details on adapting score
driven instruments for MIDI or vice-versa.


===========================================================================
midinoteonoct                                                 *midinoteonoct*

  Description

midinoteonoct is designed to simplify writing instruments that can be
used interchangeably for either score or MIDI input, and to make it
easier to adapt instruments originally written for score input to work
with MIDI input.

In general, it should be possible to write instrument definitions that
work identically with both scores and MIDI, including both MIDI files
and real-time MIDI input, without using any conditional statements, and
that take full advantage of MIDI voice messages.

Note that correlating Csound instruments with MIDI channel numbers is
done using the massign opcode for real-time performance,. For
file-driven performance, instrument numbers default to MIDI channel
number + 1, but the defaults are overridden by any MIDI program change
messages in the file.

  Syntax

midinoteonoct xoct, xvelocity

  Performance

xoct -- returns MIDI key translated to linear octaves during MIDI
activation, remains unchanged otherwise.

xvelocity -- returns MIDI velocity during MIDI activation, remains
unchanged otherwise.

If the instrument was activated by MIDI input, the opcode overwrites the
values of xoct and xvelocity with the corresponding value from MIDI
input. If the instrument was NOT activated by MIDI input, the values of
xoct and xvelocity remain unchanged.

This enables score p-fields to receive MIDI input data during MIDI
activation, and score values otherwise.

  Adapting a score-activated Csound instrument.

See the MIDI interop opcodes section for details on adapting score
driven instruments for MIDI or vice-versa.


===========================================================================
midinoteonpch                                                 *midinoteonpch*

  Description

midinoteonpch is designed to simplify writing instruments that can be
used interchangeably for either score or MIDI input, and to make it
easier to adapt instruments originally written for score input to work
with MIDI input.

In general, it should be possible to write instrument definitions that
work identically with both scores and MIDI, including both MIDI files
and real-time MIDI input, without using any conditional statements, and
that take full advantage of MIDI voice messages.

Note that correlating Csound instruments with MIDI channel numbers is
done using the massign opcode for real-time performance,. For
file-driven performance, instrument numbers default to MIDI channel
number + 1, but the defaults are overridden by any MIDI program change
messages in the file.

  Syntax

midinoteonpch xpch, xvelocity

  Performance

xpch -- returns MIDI key translated to octave.pch during MIDI
activation, remains unchanged otherwise.

xvelocity -- returns MIDI velocity during MIDI activation, remains
unchanged otherwise.

If the instrument was activated by MIDI input, the opcode overwrites the
values of xpch and xvelocity with the corresponding value from MIDI
input. If the instrument was NOT activated by MIDI input, the values of
xpch and xvelocity remain unchanged.

This enables score p-fields to receive MIDI input data during MIDI
activation, and score values otherwise.

  Adapting a score-activated Csound instrument.

See the MIDI interop opcodes section for details on adapting score
driven instruments for MIDI or vice-versa.


===========================================================================
midion2                                                             *midion2*

  Description

Sends noteon and noteoff messages to the MIDI OUT port when triggered by
a value different than zero.

  Syntax

midion2 kchn, knum, kvel, ktrig

  Performance

kchn -- MIDI channel (1-16)

knum -- MIDI note number (0-127)

kvel -- note velocity (0-127)

ktrig -- trigger input signal (normally 0)

Similar to midion, this opcode sends noteon and noteoff messages to the
MIDI out port, but only when ktrig is non-zero. This opcode is can work
together with the output of the trigger opcode.


===========================================================================
midion                                                               *midion*

  Description

Generates MIDI note messages at k-rate.

  Syntax

midion kchn, knum, kvel

  Performance

kchn -- MIDI channel number (1-16)

knum -- note number (0-127)

kvel -- velocity (0-127)

midion (k-rate note on) plays MIDI notes with current kchn, knum and
kvel. These arguments can be varied at k-rate. Each time the MIDI
converted value of any of these arguments changes, last MIDI note played
by current instance of midion is immediately turned off and a new note
with the new argument values is activated. This opcode, as well as
moscil, can generate very complex melodic textures if controlled by
complex k-rate signals.

Any number of midion opcodes can appear in the same Csound instrument,
allowing a counterpoint-style polyphony within a single instrument.


===========================================================================
midiout                                                             *midiout*

  Description

Sends a generic MIDI message to the MIDI OUT port.

  Syntax

midiout kstatus, kchan, kdata1, kdata2

  Performance

kstatus -- the type of MIDI message. Can be:

  * 128 (note off)

  * 144 (note on)

  * 160 (polyphonic aftertouch)

  * 176 (control change)

  * 192 (program change)

  * 208 (channel aftertouch)

  * 224 (pitch bend)

  * 0 when no MIDI messages must be sent to the MIDI OUT port

kchan -- MIDI channel (1-16)

kdata1, kdata2 -- message-dependent data values

midiout has no output arguments, because it sends a message to the MIDI
OUT port implicitly. It works at k-rate. It sends a MIDI message only
when kstatus is non-zero.

  Warning

Warning: Normally kstatus should be set to 0. Only when the user intends
to send a MIDI message, can it be set to the corresponding message type
number.


===========================================================================
midipitchbend                                                 *midipitchbend*

  Description

midipitchbend is designed to simplify writing instruments that can be
used interchangeably for either score or MIDI input, and to make it
easier to adapt instruments originally written for score input to work
with MIDI input.

In general, it should be possible to write instrument definitions that
work identically with both scores and MIDI, including both MIDI files
and real-time MIDI input, without using any conditional statements, and
that take full advantage of MIDI voice messages.

Note that correlating Csound instruments with MIDI channel numbers is
done using the massign opcode for real-time performance,. For
file-driven performance, instrument numbers default to MIDI channel
number + 1, but the defaults are overridden by any MIDI program change
messages in the file.

  Syntax

midipitchbend xpitchbend [, ilow] [, ihigh]

  Initialization

ilow (optional) -- optional low value after rescaling, defaults to 0.

ihigh (optional) -- optional high value after rescaling, defaults to 127.

  Performance

xpitchbend -- returns the MIDI pitch bend during MIDI activation,
remains unchanged otherwise.

If the instrument was activated by MIDI input, the opcode overwrites the
value of xpitchbend with the corresponding value from MIDI input. If the
instrument was NOT activated by MIDI input, the value of xpitchbend
remains unchanged.

This enables score p-fields to receive MIDI input data during MIDI
activation, and score values otherwise.

  Adapting a score-activated Csound instrument.

See the MIDI interop opcodes section for details on adapting score
driven instruments for MIDI or vice-versa.


===========================================================================
midipolyaftertouch                                       *midipolyaftertouch*

  Description

midipolyaftertouch is designed to simplify writing instruments that can
be used interchangeably for either score or MIDI input, and to make it
easier to adapt instruments originally written for score input to work
with MIDI input.

In general, it should be possible to write instrument definitions that
work identically with both scores and MIDI, including both MIDI files
and real-time MIDI input, without using any conditional statements, and
that take full advantage of MIDI voice messages.

Note that correlating Csound instruments with MIDI channel numbers is
done using the massign opcode for real-time performance,. For
file-driven performance, instrument numbers default to MIDI channel
number + 1, but the defaults are overridden by any MIDI program change
messages in the file.

  Syntax

midipolyaftertouch xpolyaftertouch, xcontrollervalue [, ilow] [, ihigh]

  Initialization

ilow (optional) -- optional low value after rescaling, defaults to 0.

ihigh (optional) -- optional high value after rescaling, defaults to 127.

  Performance

xpolyaftertouch -- returns MIDI polyphonic aftertouch during MIDI
activation, remains unchanged otherwise.

xcontrollervalue -- returns the value of the MIDI controller during MIDI
activation, remains unchanged otherwise.

If the instrument was activated by MIDI input, the opcode overwrites the
values of xpolyaftertouch and xcontrollervalue with the corresponding
values from MIDI input. If the instrument was NOT activated by MIDI
input, the values of xpolyaftertouch and xcontrollervalue remain unchanged.

This enables score p-fields to receive MIDI input data during MIDI
activation, and score values otherwise.

  Adapting a score-activated Csound instrument.

See the MIDI interop opcodes section for details on adapting score
driven instruments for MIDI or vice-versa.


===========================================================================
midiprogramchange                                         *midiprogramchange*

  Description

midiprogramchange is designed to simplify writing instruments that can
be used interchangeably for either score or MIDI input, and to make it
easier to adapt instruments originally written for score input to work
with MIDI input.

In general, it should be possible to write instrument definitions that
work identically with both scores and MIDI, including both MIDI files
and real-time MIDI input, without using any conditional statements, and
that take full advantage of MIDI voice messages.

Note that correlating Csound instruments with MIDI channel numbers is
done using the massign opcode for real-time performance,. For
file-driven performance, instrument numbers default to MIDI channel
number + 1, but the defaults are overridden by any MIDI program change
messages in the file.

  Syntax

midiprogramchange xprogram

  Performance

xprogram -- returns the MIDI program change value during MIDI
activation, remains unchanged otherwise.

If the instrument was activated by MIDI input, the opcode overwrites the
value of xprogram with the corresponding value from MIDI input. If the
instrument was NOT activated by MIDI input, the value of xprogram
remains unchanged.

This enables score p-fields to receive MIDI input data during MIDI
activation, and score values otherwise.

  Adapting a score-activated Csound instrument.

See the MIDI interop opcodes section for details on adapting score
driven instruments for MIDI or vice-versa.


===========================================================================
miditempo                                                         *miditempo*

  Description

Returns the current tempo at k-rate, of either the MIDI file (if
available) or the score

  Syntax

ksig  miditempo


===========================================================================
midremot                                                           *midremot*

  Description

With the midremot and midglobal opcodes you are able to perform
instruments on remote machines and control them from a master machine.
The remote opcodes are implemented using the master/client model. All
the machines involved contain the same orchestra but only the master
machine contains the information of the midi score. During the
performance the master machine sends the midi events to the clients. The
midremot opcode will send events from a source machine to one
destination if you want to send events to many destinations (broadcast)
use the midglobal opcode instead. These two opcodes can be used in
combination.

  Syntax

midremot idestination, isource, instrnum [,instrnum...] 

  Initialization

idestination -- a string that is the intended host computer (e.g.
192.168.0.100). This is the destination host which receives the events
from the given instrument.

isource -- a string that is the intended host computer (e.g.
192.168.0.100). This is the source host which generates the events of
the given instrument and sends it to the address given by idestination.

instrnum -- a list of instrument numbers which will be played on the
destination machine


===========================================================================
min                                                                     *min*

  Description

The min opcode takes any number of a-rate, k-rate or i-rate signals as
input (all of the same rate), and outputs a signal at the same rate that
is the minimum of all of the inputs. For a-rate signals, the inputs are
compared one sample at a time (i.e. min does not scan an entire ksmps
period of a signal for its local minimum as the max_k opcode does).

  Syntax

amin min ain1, ain2 [, ain3] [, ain4] [...]

kmin min kin1, kin2 [, kin3] [, kin4] [...]

imin min iin1, iin2 [, iin3] [, iin4] [...]

  Performance

ain1, ain2, ... -- a-rate signals to be compared.

kin1, kin2, ... -- k-rate signals to be compared.

iin1, iin2, ... -- i-rate signals to be compared.


===========================================================================
minabs                                                               *minabs*

  Description

The minabs opcode takes any number of a-rate or k-rate signals as input
(all of the same rate), and outputs a signal at the same rate that is
the minimum of all of the inputs. It is identical to the min opcode
except that it takes the absolute value of each input before comparing
them. Therefore, the output is always non-negative. For a-rate signals,
the inputs are compared one sample at a time (i.e. minabs does not scan
an entire ksmps period of a signal for its local minimum as the max_k
opcode does).

  Syntax

amin minabs ain1, ain2 [, ain3] [, ain4] [...]

kmin minabs kin1, kin2 [, kin3] [, kin4] [...]

  Performance

ain1, ain2, ... -- a-rate signals to be compared.

kin1, kin2, ... -- k-rate signals to be compared.


===========================================================================
minabsaccum                                                     *minabsaccum*

  Description

minabsaccum compares two audio-rate variables and stores the minimum of
their absolute values into the first.

  Syntax

minabsaccum aAccumulator, aInput

  Performance

aAccumulator -- audio variable to store the minimum value

aInput -- signal that aAccumulator is compared to

The minabsaccum opcode is designed to accumulate the minimum value from
among many audio signals that may be in different note instances,
different channels, or otherwise cannot all be compared at once using
the minabs opcode. minabsaccum is identical to minaccum except that it
takes the absolute value of aInput before the comparison. Its semantics
are similar to vincr since aAccumulator is used as both an input and an
output variable, except that minabsaccum keeps the minimum absolute
value instead of adding the signals together. minabsaccum performs the
following operation on each pair of samples:

            if  (abs(aInput) < aAccumulator)  aAccumulator = abs(aInput)

aAccumulator will usually be a global audio variable. At the end of any
given computation cycle (k-period), after its value is read and used in
some way, the accumulator variable should usually be reset to some large
enough positive value that will always be greater than the input signals
to which it is compared.


===========================================================================
minaccum                                                           *minaccum*

  Description

minaccum compares two audio-rate variables and stores the minimum value
between them into the first.

  Syntax

minaccum aAccumulator, aInput

  Performance

aAccumulator -- audio variable to store the minimum value

aInput -- signal that aAccumulator is compared to

The minaccum opcode is designed to accumulate the minimum value from
among many audio signals that may be in different note instances,
different channels, or otherwise cannot all be compared at once using
the min opcode. Its semantics are similar to vincr since aAccumulator is
used as both an input and an output variable, except that minaccum keeps
the minimum value instead of adding the signals together. minaccum
performs the following operation on each pair of samples:

            if  (aInput < aAccumulator)  aAccumulator = aInput

aAccumulator will usually be a global audio variable. At the end of any
given computation cycle (k-period), after its value is read and used in
some way, the accumulator variable should usually be reset to some large
enough positive value that will always be greater than the input signals
to which it is compared.


===========================================================================
mincer                                                               *mincer*

  Description

mincer implements phase-locked vocoder processing using function tables
containing sampled-sound sources, with GEN01, and mincer will accept
deferred allocation tables.

This opcode allows for time and frequency-independent scaling. Time is
controlled by a time index (in seconds) to the function table position
and can be moved forward and backward at any chosen speed, as well as
stopped at a given position ("frozen"). The quality of the effect is
generally improved with phase locking switched on.

mincer will also scale pitch, independently of frequency, using a
transposition factor (k-rate).

  Syntax

asig mincer atimpt, kamp, kpitch, ktab, klock[,ifftsize,idecim]

  Initialization

ifftsize -- FFT size (power-of-two), defaults to 2048.

idecim -- decimation, defaults to 4 (meaning hopsize = fftsize/4)

  Performance

atimpt -- time position of current audio sample in secs. Table reading
wraps around the ends of the function table.

kamp -- amplitude scaling

kpitch -- grain pitch scaling (1=normal pitch, < 1 lower, > 1 higher;
negative, backwards)

klock -- 0 or 1, to switch phase-locking on/off

ktab -- source signal function table. Deferred-allocation tables (see
GEN01) are accepted, but the opcode expects a mono source. Tables can be
switched at k-rate.


===========================================================================
minarray                                                           *minarray*

  Description

The minarray opcode returns the minimum value in a k-rate array, and
optional its index.

  Syntax

kmin [,kindx] minarray karray

  Performance

kmin -- variable for result.

kindx -- position (index) of result in array.

karray -- array for reading.


===========================================================================
mirror                                                               *mirror*

  Description

Reflects the signal that exceeds the low and high thresholds.

  Syntax

ares mirror asig, klow, khigh

ires mirror isig, ilow, ihigh

kres mirror ksig, klow, khigh

  Initialization

isig -- input signal

ilow -- low threshold

ihigh -- high threshold

  Performance

xsig -- input signal

klow -- low threshold

khigh -- high threshold

mirror “reflects” the signal that exceeds the low and high thresholds.

This opcode is useful in several situations, such as table indexing or
for clipping and modeling a-rate, i-rate or k-rate signals.


===========================================================================
MixerSetLevel                                                 *MixerSetLevel*

  Syntax

MixerSetLevel isend, ibuss, kgain

  Description

Sets the level at which signals from the send are added to the buss. The
actual sending of the signal to the buss is performed by the MixerSend
opcode.

  Initialization

isend -- The number of the send, for example the number of the
instrument sending the signal (but any integer can be used).

ibuss -- The number of the buss, for example the number of the
instrument receiving the signal (but any integer can be used).

Setting the gain for a buss also creates the buss.

  Performance

kgain -- The level (any real number) at which the signal from the send
will be mixed onto the buss. The default is 0.

Use of the mixer requires that instruments setting gains have smaller
numbers than instruments sending signals, and that instruments sending
signals have smaller numbers than instruments receiving those signals.
However, an instrument may have any number of sends or receives. After
the final signal is received, MixerClear must be invoked to reset the
busses before the next kperiod.


===========================================================================
MixerSetLevel_i                                             *MixerSetLevel_i*

  Syntax

MixerSetLevel_i isend, ibuss, igain

  Description

Sets the level at which signals from the send are added to the buss.
This opcode, because all parameters are irate, may be used in the
orchestra header. The actual sending of the signal to the buss is
performed by the MixerSend opcode.

  Initialization

isend -- The number of the send, for example the number of the
instrument sending the signal (but any integer can be used).

ibuss -- The number of the buss, for example the number of the
instrument receiving the signal (but any integer can be used).

igain -- The level (any real number) at which the signal from the send
will be mixed onto the buss. The default is 0.

Setting the gain for a buss also creates the buss.

  Performance

Use of the mixer requires that instruments setting gains have smaller
numbers than instruments sending signals, and that instruments sending
signals have smaller numbers than instruments receiving those signals.
However, an instrument may have any number of sends or receives. After
the final signal is received, MixerClear must be invoked to reset the
busses before the next kperiod.


===========================================================================
MixerGetLevel                                                 *MixerGetLevel*

  Syntax

kgain MixerGetLevel isend, ibuss

  Description

Gets the level at which signals from the send are being added to the
buss. The actual sending of the signal to the buss is performed by the
MixerSend opcode.

  Initialization

isend -- The number of the send, for example the number of the
instrument sending the signal.

ibuss -- The number of the buss, for example the number of the
instrument receiving the signal.

  Performance

kgain -- The level (any real number) at which the signal from the send
will be mixed onto the buss.

This opcode reports the level set by MixerSetLevel for a send and buss
pair.

Use of the mixer requires that instruments setting gains have smaller
numbers than instruments sending signals, and that instruments sending
signals have smaller numbers than instruments receiving those signals.
However, an instrument may have any number of sends or receives. After
the final signal is received, MixerClear must be invoked to reset the
busses to 0 before the next kperiod.


===========================================================================
MixerSend                                                         *MixerSend*

  Syntax

MixerSend asignal, isend, ibuss, ichannel

  Description

Mixes an arate signal into a channel of a buss.

  Initialization

isend -- The number of the send, for example the number of the
instrument sending the signal. The gain of the send is controlled by the
MixerSetLevel opcode. The reason that the sends are numbered is to
enable different levels for different sends to be set independently of
the actual level of the signals.

ibuss -- The number of the buss, for example the number of the
instrument receiving the signal.

ichannel -- The number of the channel. Each buss has |nchnls| channels.

  Performance

asignal -- The signal that will be mixed into the indicated channel of
the buss.

Use of the mixer requires that instruments setting gains have smaller
numbers than instruments sending signals, and that instruments sending
signals have smaller numbers than instruments receiving those signals.
However, an instrument may have any number of sends or receives. After
the final signal is received, MixerClear must be invoked to reset the
busses to 0 before the next kperiod.


===========================================================================
MixerReceive                                                   *MixerReceive*

  Syntax

asignal MixerReceive ibuss, ichannel

  Description

Receives an arate signal that has been mixed onto a channel of a buss.

  Initialization

ibuss -- The number of the buss, for example the number of the
instrument receiving the signal.

ichannel -- The number of the channel. Each buss has |nchnls| channels.

  Performance

asignal -- The signal that has been mixed onto the indicated channel of
the buss.

Use of the mixer requires that instruments setting gains have smaller
numbers than instruments sending signals, and that instruments sending
signals have smaller numbers than instruments receiving those signals.
However, an instrument may have any number of sends or receives. After
the final signal is received, MixerClear must be invoked to reset the
busses to 0 before the next kperiod.


===========================================================================
MixerClear                                                       *MixerClear*

  Syntax

MixerClear

  Description

Resets all channels of a buss to 0.

  Performance

Use of the mixer requires that instruments setting gains have smaller
numbers than instruments sending signals, and that instruments sending
signals have smaller numbers than instruments receiving those signals.
However, an instrument may have any number of sends or receives. After
the final signal is received, MixerClear must be invoked to reset the
busses to 0 before the next kperiod.


===========================================================================
mode                                                                   *mode*

  Description

Filters the incoming signal with the specified resonance frequency and
quality factor. It can also be seen as a signal generator for high
quality factor, with an impulse for the excitation. You can combine
several modes to built complex instruments such as bells or guitar tables.

  Syntax

aout mode ain, xfreq, xQ [, iskip]

  Initialization

iskip (optional, default=0) -- if non zero skip the initialisation of
the filter.

  Performance

aout -- filtered signal

ain -- signal to filter

xfreq -- resonant frequency of the filter

  Warning

This filter becomes unstable if sr/xfreq < pi (e.g xfreq > 14037 Hz @ 44
kHz)

xQ -- quality factor of the filter

The resonance time is roughly proportional to xQ/xfreq.

See Modal Frequency Ratios for frequency ratios of real instruments
which can be used to determine the values of xfreq.


===========================================================================
modmatrix                                                         *modmatrix*

  Description

The opcode can be used to let a large number of k-rate modulator
variables modulate a large number of k-rate parameter variables, with
arbitrary scaling of each modulator-to-parameter connection. Csound
ftables are used to hold both the input (parameter) variables, the
modulator variables, and the scaling coefficients. Output variables are
written to another Csound ftable.

  Syntax

modmatrix iresfn, isrcmodfn, isrcparmfn, imodscale, inum_mod, \\
inum_parm, kupdate

  Initialization

iresfn -- ftable number for the parameter output variables

isrcmodfn -- ftable number for the modulation source variables

isrcparmfn -- ftable number for the parameter input variables

imodscale -- scaling/routing coefficient matrix. This is also a csound
ftable, used as a matrix of inum_mod rows and inum_parm columns.

inum_mod -- number of modulation variables

inum_parm -- number of parmeter (input and output) variables.

The arguments inum_mod and inum_parm do not have to be set to
power-of-two values.

  Performance

kupdate -- flag to update the scaling coefficients. When the flag is set
to a nonzero value, the scaling coefficients are read directly from the
imodscale ftable. When the flag is set to zero, the scaling coefficients
are scanned, and an optimized scaling matrix stored internally in the
opcode.

For each modulator in isrcmodfn, scale it with the coefficient (in
imodscale) determining to what degree it should influence each
parameter. Then sum all modulators for each parameter and add the
resulting modulator value to the input parameter value read from
iscparmfn. Finally, write the output parameter values to table iresfn.

The following tables give insight into the processing performed by the
modmatrix opcode, for a simplified example using 3 parameter and 2
modulators. Let’s call the parameters "cps1", "cps2", and "cutoff", and
the modulators "lfo1" and "lfo2".

The input variables may at a given point in time have these values:

Table 12. 

        cps1    cps2    cutoff
isrcparmfn      400     800     3

... while the modulator variables have these values:

Table 13. 

        lfo1    lfo2
isrcmodfn       0.5     -0.2

The scaling/routing coefficients used:

Table 14. 

imodscale       cps1    cps2    cutoff
lfo1    40      0       -2
lfo2    -50     100     3

... and the resulting output values:

Table 15. 

        cps1    cps2    cutoff
iresfn  430     780     1.4
lfo2    -50     100     3

The output value for "cps1" is calculated as 400+(0.5*40)+(-0.2*-50),
similarly for "cps2" 800+(0.5*0)+(-0.2*100), and for cutoff:
3+(0.5*-2)+(-0.2*3)

The imodscale ftable may be specified in the score like this:

f1  0  8  -2  200 0 2 50 300 -1.5

Or more conveniently using ftgen in the orchestra:

gimodscale ftgen 0, 0, 8, -2, 200, 0, 2, 50, 300, -1.5

Obviously, the parameter and modulator variables need not be static
values, and similarly, the scaling routing coefficient table may be
continuously rewritten using opcodes like tablew.


===========================================================================
monitor                                                             *monitor*

  Description

Returns the audio spout frame (if active), otherwise it returns zero.

  Syntax

aout1 [,aout2 ... aoutX] monitor

  Performance

This opcode can be used for monitoring the output signal from csound. It
should not be used for processing the signal further.

See the entry for the fout opcode for an example of usage of monitor.


===========================================================================
moog                                                                   *moog*

  Description

An emulation of a mini-Moog synthesizer.

  Syntax

ares moog kamp, kfreq, kfiltq, kfiltrate, kvibf, kvamp, iafn, iwfn, ivfn

  Initialization

iafn, iwfn, ivfn -- three table numbers containing the attack waveform
(unlooped), the main looping wave form, and the vibrato waveform. The
files mandpluk.aiff and impuls20.aiff are suitable for the first two,
and a sine wave for the last.

  Note

The files “mandpluk.aiff” and “impuls20.aiff” are also available at
ftp://ftp.cs.bath.ac.uk/pub/dream/documentation/sounds/modelling/.

  Performance

kamp -- Amplitude of note.

kfreq -- Frequency of note played.

kfiltq -- Q of the filter, in the range 0.8 to 0.9

kfiltrate -- rate control for the filter in the range 0 to 0.0002

kvibf -- frequency of vibrato in Hertz. Suggested range is 0 to 12

kvamp -- amplitude of the vibrato


===========================================================================
moogladder                                                       *moogladder*

  Description

Moogladder is an new digital implementation of the Moog ladder filter
based on the work of Antti Huovilainen, described in the paper
"Non-Linear Digital Implementation of the Moog Ladder Filter"
(Proceedings of DaFX04, Univ of Napoli). This implementation is probably
a more accurate digital representation of the original analogue filter.

  Syntax

asig moogladder ain, kcf, kres[, istor]

asig moogladder ain, acf, kres[, istor]

asig moogladder ain, kcf, ares[, istor]

asig moogladder ain, acf, ares[, istor]

  Initialization

istor --initial disposition of internal data space. Since filtering
incorporates a feedback loop of previous output, the initial status of
the storage space used is significant. A zero value will clear the
space; a non-zero value will allow previous information to remain. The
default value is 0.

  Performance

asig -- input signal.

kcf/acf -- filter cutoff frequency

kres/ares -- resonance, generally < 1, but not limited to it. Higher
than 1 resonance values might cause aliasing, analogue synths generally
allow resonances to be above 1.


===========================================================================
moogladder2                                                     *moogladder2*

  Description

Moogladder2 is an new digital implementation of the Moog ladder filter
based on the work of Antti Huovilainen, described in the paper
"Non-Linear Digital Implementation of the Moog Ladder Filter"
(Proceedings of DaFX04, Univ of Napoli). This implementation uses
approximations to the tanh function and so is faster but less accurate
than moogladder.

  Syntax

asig moogladder2 ain, kcf, kres[, istor]

asig moogladder2 ain, acf, kres[, istor]

asig moogladder2 ain, kcf, ares[, istor]

asig moogladder2 ain, acf, ares[, istor]

  Initialization

istor --initial disposition of internal data space. Since filtering
incorporates a feedback loop of previous output, the initial status of
the storage space used is significant. A zero value will clear the
space; a non-zero value will allow previous information to remain. The
default value is 0.

  Performance

asig -- input signal.

kcf/acf -- filter cutoff frequency

kres/ares -- resonance, generally < 1, but not limited to it. Higher
than 1 resonance values might cause aliasing, analogue synths generally
allow resonances to be above 1.


===========================================================================
moogvcf                                                             *moogvcf*

  Description

A digital emulation of the Moog diode ladder filter configuration.

  Syntax

ares moogvcf asig, xfco, xres [,iscale, iskip]

  Initialization

iscale (optional, default=1) -- internal scaling factor. Use if asig is
not in the range +/-1. Input is first divided by iscale, then output is
mutliplied iscale. Default value is 1. (New in Csound version 3.50)

iskip (optional, default=0) -- if non zero skip the initialisation of
the filter. (New in Csound version 4.23f13 and 5.0)

  Performance

asig -- input signal

xfco -- filter cut-off frequency in Hz. As of version 3.50, may i-,k-,
or a-rate.

xres -- amount of resonance. Self-oscillation occurs when xres is
approximately one. As of version 3.50, may a-rate, i-rate, or k-rate.

moogvcf is a digital emulation of the Moog diode ladder filter
configuration. This emulation is based loosely on the paper “Analyzing
the Moog VCF with Considerations for Digital Implementation” by Stilson
and Smith (CCRMA). This version was originally coded in Csound by Josep
Comajuncosas. Some modifications and conversion to C were done by Hans
Mikelson.

  Warning

Before version 6.02 this filter required that the input signal be
normalized to one. This can be easily achieved using 0dbfs, like this:

ares moogvcf asig, kfco, kres, 0dbfs

You can also use moogvcf2 which defaults scaling to 0dbfs.


===========================================================================
moogvcf2                                                           *moogvcf2*

  Description

A digital emulation of the Moog diode ladder filter configuration.

  Syntax

ares moogvcf2 asig, xfco, xres [,iscale, iskip]

  Initialization

iscale (optional, default=0dBfs) -- internal scaling factor, as the
operation of the code requires the signal to be in the range +/-1. Input
is first divided by iscale, then output is mutliplied by iscale.

iskip (optional, default=0) -- if non zero skip the initialisation of
the filter.

  Performance

asig -- input signal

xfco -- filter cut-off frequency in Hz. which may be i-,k-, or a-rate.

xres -- amount of resonance. Self-oscillation occurs when xres is
approximately one. May be a-rate, i-rate, or k-rate.

moogvcf2 is a digital emulation of the Moog diode ladder filter
configuration. This emulation is based loosely on the paper “Analyzing
the Moog VCF with Considerations for Digital Implementation” by Stilson
and Smith (CCRMA). This version was originally coded in Csound by Josep
Comajuncosas. Some modifications and conversion to C were done by Hans
Mikelson and then adjusted.

moogvcf2 is identical to moogvcf, except that the iscale parameter
defaults to 0dbfs instead of 0, guaranteeing that amplitude will usually
be OK.


===========================================================================
moscil                                                               *moscil*

  Description

Sends a stream of the MIDI notes.

  Syntax

moscil kchn, knum, kvel, kdur, kpause

  Performance

kchn -- MIDI channel number (1-16)

knum -- note number (0-127)

kvel -- velocity (0-127)

kdur -- note duration in seconds

kpause -- pause duration after each noteoff and before new note in seconds

moscil and midion are the most powerful MIDI OUT opcodes. moscil (MIDI
oscil) plays a stream of notes of kdur duration. Channel, pitch,
velocity, duration and pause can be controlled at k-rate, allowing very
complex algorithmically generated melodic lines. When current instrument
is deactivated, the note played by current instance of moscil is
forcedly truncated.

Any number of moscil opcodes can appear in the same Csound instrument,
allowing a counterpoint-style polyphony within a single instrument.


===========================================================================
mp3in                                                                 *mp3in*

  Description

Reads mono or stereo audio data from an external MP3 file.

  Syntax

ar1, ar2 mp3in ifilcod[, iskptim, iformat, iskipinit, ibufsize]

ar1 mp3in ifilcod[, iskptim, iformat, iskipinit, ibufsize]

  Initialization

ifilcod -- integer or character-string denoting the source soundfile
name. An integer denotes the file soundin.filcod ; a character-string
(in double quotes, spaces permitted) gives the filename itself,
optionally a full pathname. If not a full path, the named file is sought
first in the current directory, then in that given by the environment
variable SSDIR (if defined) then by SFDIR.

iskptim (optional) -- time in seconds of input sound to be skipped. The
default value is 0.

iformat (optional) -- specifies the audio data file format: currently
not implemented and always defaults to stereo.

iskipinit (optional) -- switches off all initialisation if non zero
(default =0).

ibuffersize (optional) -- sets the internal buffer size for reading. If
the value is omitted, zero or negative it defaults to 4096 bytes.

  Performance

Reads audio data from an external MP3 file.


===========================================================================
mp3len                                                               *mp3len*

  Description

Returns the length of an MP3 sound file.

  Syntax

ir mp3len ifilcod

  Initialization

ifilcod -- sound file to be queried

  Performance

mp3len returns the length of the sound file ifilcod in seconds.


===========================================================================
mp3scal                                                             *mp3scal*

  Description

mp3scal implements phase-locked vocoder processing from mp3-format disk
files, resampling if necessary.

This opcode allows for time and frequency-independent scaling. Time is
advanced internally. The quality of the effect is generally improved
with phase locking switched on.

mp3scal will also scale pitch, independently of frequency, using a
transposition factor (k-rate).

  Syntax

asig, asig2 mp3scal Sfile,ktimescal,kpitch, kamp [,iskip,ifftsize, idecim, ilock]

  Initialization

Sfile -- source soundfile stereo mp3 files.

ifftsize -- FFT size (power-of-two), defaults to 2048.

idecim -- decimation, defaults to 4 (meaning hopsize = fftsize/4)

iskip -- skiptime in seconds, defaults to 1.

ilock -- 0 or 1, to switch phase-locking on/off, defaults to 1.

  Performance

ktimescal -- timescaling ratio, < 1 stretch, > 1 contract. Non-negative
numbers only.

kamp -- amplitude scaling

kpitch -- grain pitch scaling (1=normal pitch, < 1 lower, > 1 higher;
negative, backwards)


===========================================================================
mpulse                                                               *mpulse*

  Description

Generates a set of impulses of amplitude kamp separated by kintvl
seconds (or samples if kintvl is negative). The first impulse is
generated after a delay of ioffset seconds.

  Syntax

ares mpulse kamp, kintvl [, ioffset]

  Initialization

ioffset (optional, default=0) -- the delay before the first impulse. If
it is negative, the value is taken as the number of samples, otherwise
it is in seconds. Default is zero.

  Performance

kamp -- amplitude of the impulses generated

kintvl -- Interval of time in seconds (or samples if kintvl is negative)
to the next pulse.

After the initial delay, an impulse of kamp amplitude is generated as a
single sample. Immediately after generating the impulse, the time of the
next one is determined from the value of kintvl at that precise moment.
This means that any changes in kintvl between impulses are discarded. If
kintvl is zero, there is an infinite wait to the next impulse. If kintvl
is negative, the interval is counted in number of samples rather than
seconds.


===========================================================================
mrtmsg                                                               *mrtmsg*

  Description

Send system real-time messages to the MIDI OUT port.

  Syntax

mrtmsg imsgtype

  Initialization

imsgtype -- type of real-time message:

  * 1 sends a START message (0xFA);

  * 2 sends a CONTINUE message (0xFB);

  * 0 sends a STOP message (0xFC);

  * -1 sends a SYSTEM RESET message (0xFF);

  * -2 sends an ACTIVE SENSING message (0xFE)

  Performance

Sends a real-time message once, in init stage of current instrument.
imsgtype parameter is a flag to indicate the message type.


===========================================================================
multitap                                                           *multitap*

  Description

Multitap delay line implementation.

  Syntax

ares multitap asig [, itime1, igain1] [, itime2, igain2] [...]

  Initialization

The arguments itime and igain set the position and gain of each tap.

The delay line is fed by asig.


===========================================================================
mute                                                                   *mute*

  Description

Mutes/unmutes new instances of a given instrument.

  Syntax

mute insnum [, iswitch]

mute "insname" [, iswitch]

  Initialization

insnum -- instrument number. Equivalent to p1 in a score i statement.

“insname” -- A string (in double-quotes) representing a named instrument.

iswitch (optional, default=0) -- represents a switch to mute/unmute an
instrument. A value of 0 will mute new instances of an instrument, other
values will unmute them. The default value is 0.

  Performance

All new instances of instrument inst will me muted (iswitch = 0) or
unmuted (iswitch not equal to 0). There is no difficulty with muting
muted instruments or unmuting unmuted instruments. The mechanism is the
same as used by the score q statement. For example, it is possible to
mute in the score and unmute in some instrument.

Muting/Unmuting is indicated by a message (depending on message level).


===========================================================================
mvchpf                                                               *mvchpf*

  Description

Mvchpf is an digital implementation of the 4th-order (24 dB/oct) Moog
high-pass filter, originally written by Fons Andriaensen. According to
the author, mvchpf "...is based on the voltage controlled highpass
filter by Robert Moog. again with some attention to the nonlinear effects."

  Syntax

asig mvchpf ain, xcf[, istor]

  Initialization

istor --initial disposition of internal data space. Since filtering
incorporates a feedback loop of previous output, the initial status of
the storage space used is significant. A zero value will clear the
space; a non-zero value will allow previous information to remain. The
default value is 0.

  Performance

ain -- input signal.

xcf -- filter cutoff frequency. The useful range is around six octaves
below and above middle C (pch 8.00).


===========================================================================
mvclpf1                                                             *mvclpf1*

  Description

Mvclpf1 is an digital implementation of the 4th-order (24 dB/oct) Moog
ladder filter originally written by Fons Andriaensen. According to the
author, mvclpf1 "is a fairly simple design, and it does not even pretend
to come close the 'real thing'. It uses a very crude approximation of
the non-linear resistor in the first filter section only. [...] [I]t's
[a] cheap (in terms of CPU usage) general purpose 24 dB/oct lowpass
filter that could be useful".

  Syntax

asig mvclpf1 ain, xcf, xres[,istor]

  Initialization

istor --initial disposition of internal data space. Since filtering
incorporates a feedback loop of previous output, the initial status of
the storage space used is significant. A zero value will clear the
space; a non-zero value will allow previous information to remain. The
default value is 0.

  Performance

ain -- input signal.

xcf -- filter cutoff frequency. The useful range is around six octaves
below and above middle C (pch 8.00).

xres -- resonance, limited to the interval [0,1].


===========================================================================
mvclpf2                                                             *mvclpf2*

  Description

Mvclpf2 is an digital implementation of the 4th-order (24 dB/oct) Moog
ladder filter originally written by Fons Andriaensen. According to the
author, mvclpf2 "uses five non-linear elements, in the input and in all
four filter sections. It works by using the derivative of the
nonlinearity (for which 1 / (1 + x * x) is reasonable approximation).
The main advantage of this is that only one evaluation of the non-linear
function is required for each section".

  Syntax

asig mvclpf2 ain, xcf, xres[, istor]

  Initialization

istor --initial disposition of internal data space. Since filtering
incorporates a feedback loop of previous output, the initial status of
the storage space used is significant. A zero value will clear the
space; a non-zero value will allow previous information to remain. The
default value is 0.

  Performance

ain -- input signal.

xcf -- filter cutoff frequency. The useful range is around six octaves
below and above middle C (pch 8.00).

xres -- resonance, limited to the interval [0,1].


===========================================================================
mvclpf3                                                             *mvclpf3*

  Description

Mvclpf3 is an digital implementation of the 4th-order (24 dB/oct) Moog
ladder filter originally written by Fons Andriaensen. According to the
author, mvclpf3 "is based on mvclpf2 , with two differences. It uses the
the technique described by Stilson and Smith to extend the constant-Q
range, and the internal sample frequency is doubled, giving a better
approximation to the non-linear behaviour at high freqencies. This
version has high Q over the entire frequency range and will oscillate up
to above 10 kHz, while the two others show a decreasing Q at high
frequencies. Mvclpf3 is reasonably well tuned, and can be 'played' as a
VCO up to at least 5 kHz".

  Syntax

asig mvclpf3 ain, xcf, xres[, istor]

  Initialization

istor --initial disposition of internal data space. Since filtering
incorporates a feedback loop of previous output, the initial status of
the storage space used is significant. A zero value will clear the
space; a non-zero value will allow previous information to remain. The
default value is 0.

  Performance

ain -- input signal.

xcf -- filter cutoff frequency. The useful range is around six octaves
below and above middle C (pch 8.00).

xres -- resonance, limited to the interval [0,1].


===========================================================================
mvclpf4                                                             *mvclpf4*

  Description

Mvclpf4 is an digital implementation of the 4th-order (24 dB/oct) Moog
ladder filter originally written by Fons Andriaensen. It is a version of
the mvclpf3 opcode with four outputs, for 6dB, 12dB, 18dB, and 24
dB/octave responses.

  Syntax

asig1,asig2,asig3,asig4 mvclpf4 ain, xcf, xres[, istor]

  Initialization

istor --initial disposition of internal data space. Since filtering
incorporates a feedback loop of previous output, the initial status of
the storage space used is significant. A zero value will clear the
space; a non-zero value will allow previous information to remain. The
default value is 0.

  Performance

asig1 -- 6dB/oct low-pass response output.

asig2 -- 12dB/oct low-pass response output.

asig3 -- 18dB/oct low-pass response output..

asig4 -- 24dB/oct low-pass response output.

ain -- input signal.

xcf -- filter cutoff frequency. The useful range is around six octaves
below and above middle C (pch 8.00).

xres -- resonance, limited to the interval [0,1].


===========================================================================
mxadsr                                                               *mxadsr*

  Description

Calculates the classical ADSR envelope using the expsegr mechanism.

  Syntax

ares mxadsr iatt, idec, islev, irel [, idel] [, ireltim]

kres mxadsr iatt, idec, islev, irel [, idel] [, ireltim]

  Initialization

iatt -- duration of attack phase

idec -- duration of decay

islev -- level for sustain phase

irel -- duration of release phase

idel (optional, default=0) -- period of zero before the envelope starts

ireltim (optional, default=-1) -- Control release time after receiving a
MIDI noteoff event. If less than zero, the longest release time given in
the current instrument is used. If zero or more, the given value will be
used for release time. Its default value is -1. (New in Csound 3.59 -
not yet properly tested)

  Performance

The envelope is in the range 0 to 1 and may need to be scaled further.
The envelope may be described as:

Picture of an ADSR envelope.

Picture of an ADSR envelope.

The length of the sustain is calculated from the length of the note.
This means adsr is not suitable for use with MIDI events. The opcode
madsr uses the linsegr mechanism, and so can be used in MIDI
applications. The opcode mxadsr is identical to madsr except it uses
exponential, rather than linear, line segments.

You can use other pre-made envelopes which start a release segment upon
receiving a note off message, like linsegr and expsegr, or you can
construct more complex envelopes using xtratim and release. Note that
you don't need to use xtratim if you are using mxadsr, since the time is
extended automatically.

mxadsr is new in Csound version 3.51.


===========================================================================
nchnls                                                               *nchnls*

  Description

These statements are global value assignments, made at the beginning of
an orchestra, before any instrument block is defined. Their function is
to set certain reserved symbol variables that are required for
performance. Once set, these reserved symbols can be used in expressions
anywhere in the orchestra.

  Syntax

nchnls = iarg

  Initialization

nchnls = (optional) -- set number of channels of audio output to iarg.
(1 = mono, 2 = stereo, 4 = quadraphonic.) The default value is 1 (mono).

In addition, any global variable can be initialized by an init-time
assignment anywhere before the first instr statement. All of the above
assignments are run as instrument 0 (i-pass only) at the start of real
performance.


===========================================================================
nchnls_hw                                                         *nchnls_hw*

  Description

Returns the maximum number of audio channels in the underlying hardware.
This does not necessarily correspond to the number of channels used by
Csound (set by nchnls and nchnls_i).

  Syntax

idacc,iadcc nchnls_hw

  Initialization

On init-pass idacc will contain the number of channels in the output
device, and iadcc, the number of input channels. These will correspond
to the currently selected/in-use hardware devices.


===========================================================================
nchnls_i                                                           *nchnls_i*

  Description

These statements are global value assignments, made at the beginning of
an orchestra, before any instrument block is defined. Their function is
to set certain reserved symbol variables that are required for
performance. Once set, these reserved symbols can be used in expressions
anywhere in the orchestra.

  Syntax

nchnls_i = iarg

  Initialization

nchnls_i = (optional) -- set number of channels of audio input to iarg.
(1 = mono, 2 = stereo, 4 = quadraphonic.) The default value is the valus
of nchnls.

In addition, any global variable can be initialized by an init-time
assignment anywhere before the first instr statement. All of the above
assignments are run as instrument 0 (i-pass only) at the start of real
performance.


===========================================================================
nestedap                                                           *nestedap*

  Description

Three different nested all-pass filters, useful for implementing reverbs.

  Syntax

ares nestedap asig, imode, imaxdel, idel1, igain1 [, idel2] [, igain2] \
      [, idel3] [, igain3] [, istor]

  Initialization

imode -- operating mode of the filter:

  * 1 = simple all-pass filter

  * 2 = single nested all-pass filter

  * 3 = double nested all-pass filter

idel1, idel2, idel3 -- delay times of the filter stages. Delay times are
in seconds and must be greater than zero. idel1 must be greater than the
sum of idel2 and idel3.

igain1, igain2, igain3 -- gain of the filter stages.

imaxdel -- will be necessary if k-rate delays are implemented. Not
currently used.

istor -- Skip initialization if non-zero (default: 0).

  Performance

asig -- input signal

If imode = 1, the filter takes the form:

Picture of nestedap imode 1 filter.

Picture of imode 1 filter.

If imode = 2, the filter takes the form:

Picture of nestedap imode 2 filter.

Picture of imode 2 filter.

If imode = 3, the filter takes the form:

Picture of nestedap imode 3 filter.

Picture of imode 3 filter.


===========================================================================
nlfilt                                                               *nlfilt*

  Description

Implements the filter:

Y{n} =a Y{n-1} + b Y{n-2} + d Y^2{n-L} + X{n} - C 

described in Dobson and Fitch (ICMC'96)

  Syntax

ares nlfilt ain, ka, kb, kd, kC, kL

  Performance

 1. Non-linear effect. The range of parameters are:

      a = b = 0
      d = 0.8, 0.9, 0.7
      C = 0.4, 0.5, 0.6
      L = 20

This affects the lower register most but there are audible effects
    over the whole range. We suggest that it may be useful for coloring
    drums, and for adding arbitrary highlights to notes.

 2. Low Pass with non-linear. The range of parameters are:

      a = 0.4
      b = 0.2
      d = 0.7
      C = 0.11
      L = 20, ... 200

There are instability problems with this variant but the effect is 
    more pronounced of the lower register, but is otherwise much like
    the pure comb. Short values of L can add attack to a sound.

 3. High Pass with non-linear. The range of parameters are:

      a = 0.35
      b = -0.3
      d = 0.95
      C = 0,2, ... 0.4
      L = 200

 4. High Pass with non-linear. The range of parameters are:

      a = 0.7
      b = -0.2, ... 0.5
      d = 0.9
      C = 0.12, ... 0.24
      L = 500, 10

The high pass version is less likely to oscillate. It adds
    scintillation to medium-high registers. With a large delay L it is a
    little like a reverberation, while with small values there appear to
    be formant-like regions. There are arbitrary color changes and
    resonances as the pitch changes. Works well with individual notes.

  Warning

The "useful" ranges of parameters are not yet mapped.


===========================================================================
nlfilt2                                                             *nlfilt2*

  Description

Implements the filter:

Y{n} =tanh(a Y{n-1} + b Y{n-2} + d Y^2{n-L} + X{n} - C)

described in Dobson and Fitch (ICMC'96) as modified by Risto Holopainen.

  Syntax

ares nlfilt2 ain, ka, kb, kd, kC, kL

  Performance

 1. Non-linear effect. The range of parameters are:

      a = b = 0
      d = 0.8, 0.9, 0.7
      C = 0.4, 0.5, 0.6
      L = 20

===========================================================================
This affects the lower register most but there are audible effects
    over the whole range. We suggest that it may be useful for coloring
    drums, and for adding arbitrary highlights to notes.

 2. Low Pass with non-linear. The range of parameters are:

      a = 0.4
      b = 0.2
      d = 0.7
      C = 0.11
      L = 20, ... 200

There are instability problems with this variant but the effect is
    more pronounced of the lower register, but is otherwise much like
    the pure comb. Short values of L can add attack to a sound.

 3. High Pass with non-linear. The range of parameters are:

      a = 0.35
      b = -0.3
      d = 0.95
      C = 0,2, ... 0.4
      L = 200

 4. High Pass with non-linear. The range of parameters are:

      a = 0.7
      b = -0.2, ... 0.5
      d = 0.9
      C = 0.12, ... 0.24
      L = 500, 10

The high pass version is less likely to oscillate. It adds 
    scintillation to medium-high registers. With a large delay L it is a
    little like a reverberation, while with small values there appear to
    be formant-like regions. There are arbitrary color changes and
    resonances as the pitch changes. Works well with individual notes.

  Warning

The "useful" ranges of parameters are not yet mapped.


===========================================================================
noise                                                                 *noise*

  Description

A white noise generator with an IIR lowpass filter.

  Syntax

ares noise xamp, kbeta

  Performance

xamp -- amplitude of final output

kbeta -- beta of the lowpass filter. Should be in the range of -1 to 1,
exclusive of the end-points.

The filter equation is:

[Filter equation for filter in noise opcode.]

where x_n is the original white noise and y_n is lowpass filtered noise.
The higher β is, the lower the filter's cut-off frequency. The cutoff
frequency is roughly sr * ((1-kbeta)/2).


===========================================================================
noteoff                                                             *noteoff*

  Description

Send a noteoff message to the MIDI OUT port.

  Syntax

noteoff ichn, inum, ivel

  Initialization

ichn -- MIDI channel number (1-16)

inum -- note number (0-127)

ivel -- velocity (0-127)

  Performance

noteon (i-rate note on) and noteoff (i-rate note off) are the simplest
MIDI OUT opcodes. noteon sends a MIDI noteon message to MIDI OUT port,
and noteoff sends a noteoff message. A noteon opcode must always be
followed by an noteoff with the same channel and number inside the same
instrument, otherwise the note will play endlessly.

These noteon and noteoff opcodes are useful only when introducing a
timout statement to play a non-zero duration MIDI note. For most
purposes, it is better to use noteondur and noteondur2.


===========================================================================
noteon                                                               *noteon*

  Description

Send a noteon message to the MIDI OUT port.

  Syntax

noteon ichn, inum, ivel

  Initialization

ichn -- MIDI channel number (1-16)

inum -- note number (0-127)

ivel -- velocity (0-127)

  Performance

noteon (i-rate note on) and noteoff (i-rate note off) are the simplest
MIDI OUT opcodes. noteon sends a MIDI noteon message to MIDI OUT port,
and noteoff sends a noteoff message. A noteon opcode must always be
followed by an noteoff with the same channel and number inside the same
instrument, otherwise the note will play endlessly.

These noteon and noteoff opcodes are useful only when introducing a
timout statement to play a non-zero duration MIDI note. For most
purposes, it is better to use noteondur and noteondur2.


===========================================================================
noteondur2                                                       *noteondur2*

  Description

Sends a noteon and a noteoff MIDI message both with the same channel,
number and velocity.

  Syntax

noteondur2 ichn, inum, ivel, idur

  Initialization

ichn -- MIDI channel number (1-16)

inum -- note number (0-127)

ivel -- velocity (0-127)

idur -- how long, in seconds, this note should last.

  Performance

noteondur2 (i-rate note on with duration) sends a noteon and a noteoff
MIDI message both with the same channel, number and velocity. Noteoff
message is sent after idur seconds are elapsed by the time noteondur2
was active.

noteondur differs from noteondur2 in that noteondur truncates note
duration when current instrument is deactivated by score or by real-time
playing, while noteondur2 will extend performance time of current
instrument until idur seconds have elapsed. In real-time playing, it is
suggested to use noteondur also for undefined durations, giving a large
idur value.

Any number of noteondur2 opcodes can appear in the same Csound
instrument, allowing chords to be played by a single instrument.


===========================================================================
noteondur                                                         *noteondur*

  Description

Sends a noteon and a noteoff MIDI message both with the same channel,
number and velocity.

  Syntax

noteondur ichn, inum, ivel, idur

  Initialization

ichn -- MIDI channel number (1-16)

inum -- note number (0-127)

ivel -- velocity (0-127)

idur -- how long, in seconds, this note should last.

  Performance

noteondur (i-rate note on with duration) sends a noteon and a noteoff
MIDI message both with the same channel, number and velocity. Noteoff
message is sent after idur seconds are elapsed by the time noteondur was
active.

noteondur differs from noteondur2 in that noteondur truncates note
duration when current instrument is deactivated by score or by real-time
playing, while noteondur2 will extend performance time of current
instrument until idur seconds have elapsed. In real-time playing, it is
suggested to use noteondur also for undefined durations, giving a large
idur value.

Any number of noteondur opcodes can appear in the same Csound
instrument, allowing chords to be played by a single instrument.


===========================================================================
notnum                                                               *notnum*

  Description

Get a note number from a MIDI event.

  Syntax

ival notnum

  Performance

Get the MIDI byte value (0 - 127) denoting the note number of the
current event.


===========================================================================
nreverb                                                             *nreverb*

  Description

This is a reverberator consisting of 6 parallel comb-lowpass filters
being fed into a series of 5 allpass filters. nreverb replaces reverb2
(version 3.48) and so both opcodes are identical.

  Syntax

ares nreverb asig, ktime, khdif [, iskip] [,inumCombs] [, ifnCombs] \
      [, inumAlpas] [, ifnAlpas]

  Initialization

iskip (optional, default=0) -- Skip initialization if present and non-zero.

inumCombs (optional) -- number of filter constants in comb filter. If
omitted, the values default to the nreverb constants. New in Csound
version 4.09.

ifnCombs - function table with inumCombs comb filter time values,
followed the same number of gain values. The ftable should not be
rescaled (use negative fgen number). Positive time values are in
seconds. The time values are converted internally into number of
samples, then set to the next greater prime number. If the time is
negative, it is interpreted directly as time in sample frames, and no
processing is done (except negation). New in Csound version 4.09.

inumAlpas, ifnAlpas (optional) -- same as inumCombs/ifnCombs, for
allpass filter. New in Csound 4.09.

  Performance

The input signal asig is reverberated for ktime seconds. The parameter
khdif controls the high frequency diffusion amount. The values of khdif
should be from 0 to 1. If khdif is set to 0 the all the frequencies
decay with the same speed. If khdif is 1, high frequencies decay faster
than lower ones. If ktime is inadvertently set to a non-positive number,
ktime will be reset automatically to 0.01. (New in Csound version 4.07.)

As of Csound version 4.09, nreverb may read any number of comb and
allpass filter from an ftable.


===========================================================================
nrpn                                                                   *nrpn*

  Description

Sends a NPRN (Non-Registered Parameter Number) message to the MIDI OUT
port each time one of the input arguments changes.

  Syntax

nrpn kchan, kparmnum, kparmvalue

  Performance

kchan -- MIDI channel (1-16)

kparmnum -- number of NRPN parameter

kparmvalue -- value of NRPN parameter

This opcode sends new message when the MIDI translated value of one of
the input arguments changes. It operates at k-rate. Useful with the MIDI
instruments that recognize NRPNs (for example with the newest
sound-cards with internal MIDI synthesizer such as SB AWE32, AWE64, GUS
etc. in which each patch parameter can be changed during the performance
via NRPN)


===========================================================================
nsamp                                                                 *nsamp*

  Description

Returns the number of samples loaded into a stored function table number.

  Syntax

nsamp(x) (init-rate args only)

  Performance

Returns the number of samples loaded into stored function table number x
by GEN01. This is useful when a sample is shorter than the power-of-two
function table that holds it. New in Csound version 3.49.

As of Csound version 5.02, nsamp works with deferred-length function
tables (see GEN01).

nsamp differs from ftlen in that nsamp gives the number of sample frames
loaded, while ftlen gives the total number of samples. For example, with
a stereo sound file of 10000 samples, ftlen() would return 19999 (i.e. a
total of 20000 mono samples, not including a guard point), but nsamp()
returns 10000.


===========================================================================
nstance                                                             *nstance*

  Description

Schedules a new instrument nstance, returning a handle that can be used
later to refer directly to the running nstance. This opcode is similar
to schedule, but has the added facility of retrieving the nstance handle.

  Syntax

iHandle nstance insnum, iwhen, idur [, ip4] [, ip5] [...]

iHandle nstance "insname", iwhen, idur [, ip4] [, ip5] [...]

  Initialization

iHandle -- this variable will contain a handle to the event instance. It
can be used, for example, to stop the given instrument instance via the
turnoff opcode. Note that the instance handle is only valid once the
instrument is initialised.

insnum -- instrument number. Equivalent to p1 in a score i statement.
insnum must be a number greater than the number of the calling instrument.

“insname” -- A string (in double-quotes) representing a named instrument.

iwhen -- start time of the new event. Equivalent to p2 in a score i
statement. iwhen must be nonnegative. If iwhen is zero, insum must be
greater than or equal to the p1 of the current instrument.

idur -- duration of event. Equivalent to p3 in a score i statement.

ip4, ip5, ... -- Equivalent to p4, p5, etc., in a score i statement.

  Performance

nstance adds a new score event. The arguments, including options, are
the same as in a score. The iwhen time (p2) is measured from the time of
this event.

If the duration is zero or negative the new event is of MIDI type, and
inherits the release sub-event from the scheduling instruction.

  Note

Note that the nstance opcode can't accept string p-fields. If you need
to pass strings when instantiating an instrument, use the scoreline or
scoreline_i opcode.


===========================================================================
nstrnum                                                             *nstrnum*

  Description

Returns the number of a named instrument.

  Syntax

insno nstrnum "name"

  Initialization

insno -- the instrument number of the named instrument.

  Performance

"name" -- the named instrument's name.

If an instrument with the specified name does not exist, an init error
occurs, and -1 is returned.


===========================================================================
ntrpol                                                               *ntrpol*

  Description

Calculates the weighted mean value (i.e. linear interpolation) of two
input signals

  Syntax

ares ntrpol asig1, asig2, kpoint [, imin] [, imax]

ires ntrpol isig1, isig2, ipoint [, imin] [, imax]

kres ntrpol ksig1, ksig2, kpoint [, imin] [, imax]

  Initialization

imin -- minimum xpoint value (optional, default 0)

imax -- maximum xpoint value (optional, default 1)

  Performance

xsig1, xsig2 -- input signals

xpoint -- interpolation point between the two values

ntrpol opcode outputs the linear interpolation between two input values.
xpoint is the distance of evaluation point from the first value. With
the default values of imin and imax, (0 and 1) a zero value indicates no
distance from the first value and the maximum distance from the second
one. With a 0.5 value, ntrpol will output the mean value of the two
inputs, indicating the exact half point between xsig1 and xsig2. A 1
value indicates the maximum distance from the first value and no
distance from the second one. The range of xpoint can be also defined
with imin and imax to make its management easier.

These opcodes are useful for crossfading two signals.


===========================================================================
octave                                                               *octave*

  Description

Calculates a factor to raise/lower a frequency by a given amount of
octaves.

  Syntax

octave(x)

This function works at a-rate, i-rate, and k-rate.

  Initialization

x -- a value expressed in octaves.

  Performance

The value returned by the octave function is a factor. You can multiply
a frequency by this factor to raise/lower it by the given amount of
octaves.


===========================================================================
octcps                                                               *octcps*

  Description

Converts a cycles-per-second value to octave-point-decimal.

  Syntax

octcps (cps)  (init- or control-rate args only)

where the argument within the parentheses may be a further expression.

  Performance

octcps and its related opcodes are really value converters with a
special function of manipulating pitch data.

Data concerning pitch and frequency can exist in any of the following
forms:

Table 16. Pitch and Frequency Values

Name    Abbreviation
octave point pitch-class (8ve.pc)       pch
octave point decimal    oct
cycles per second       cps
Midi note number (0-127)        midinn

The first two forms consist of a whole number, representing octave
registration, followed by a specially interpreted fractional part. For
pch, the fraction is read as two decimal digits representing the 12
equal-tempered pitch classes from .00 for C to .11 for B. For oct, the
fraction is interpreted as a true decimal fractional part of an octave.
The two fractional forms are thus related by the factor 100/12. In both
forms, the fraction is preceded by a whole number octave index such that
8.00 represents Middle C, 9.00 the C above, etc. Midi note number values
range between 0 and 127 (inclusively) with 60 representing Middle C, and
are usually whole numbers. Thus A440 can be represented alternatively by
440 (cps), 69 (midinn), 8.09 (pch), or 8.75 (oct). Microtonal divisions
of the pch semitone can be encoded by using more than two decimal places.

The mnemonics of the pitch conversion units are derived from morphemes
of the forms involved, the second morpheme describing the source and the
first morpheme the object (result). Thus cpspch(8.09) will convert the
pitch argument 8.09 to its cps (or Hertz) equivalent, giving the value
of 440. Since the argument is constant over the duration of the note,
this conversion will take place at i-time, before any samples for the
current note are produced.

By contrast, the conversion cpsoct(8.75 + k1) which gives the value of
A440 transposed by the octave interval k1. The calculation will be
repeated every k-period since that is the rate at which k1 varies.

  Note

The conversion from pch, oct, or midinn into cps is not a linear
operation but involves an exponential process that could be
time-consuming when executed repeatedly. Csound now uses a built-in
table lookup to do this efficiently, even at audio rates. Because the
table index is truncated without interpolation, pitch resolution when
using one of these opcodes is limited to 8192 discrete and equal
divisions of the octave, and some pitches of the standard 12-tone
equally-tempered scale are very slightly mistuned (by at most 0.15 cents).


===========================================================================
octmidi                                                             *octmidi*

  Description

Get the note number, in octave-point-decimal units, of the current MIDI
event.

  Syntax

ioct octmidi

  Performance

Get the note number of the current MIDI event, expressed in
octave-point-decimal units, for local processing.

  octmidi vs. octmidinn

The octmidi opcode only produces meaningful results in a Midi-activated
note (either real-time or from a Midi score with the -F flag). With
octmidi, the Midi note number value is taken from the Midi event that is
internally associated with the instrument instance. On the other hand,
the octmidinn opcode may be used in any Csound instrument instance
whether it is activated from a Midi event, score event, line event, or
from another instrument. The input value for octmidinn might for example
come from a p-field in a textual score or it may have been retrieved
from the real-time Midi event that activated the current note using the
notnum opcode.


===========================================================================
octmidib                                                           *octmidib*

  Description

Get the note number of the current MIDI event and modify it by the
current pitch-bend value, express it in octave-point-decimal.

  Syntax

ioct octmidib [irange]

koct octmidib [irange]

  Initialization

irange (optional) -- the pitch bend range in semitones

  Performance

Get the note number of the current MIDI event, modify it by the current
pitch-bend value, and express the result in octave-point-decimal units.
Available as an i-time value or as a continuous k-rate value.


===========================================================================
octmidinn                                                         *octmidinn*

  Description

Converts a Midi note number value to octave-point-decimal.

  Syntax

octmidinn (MidiNoteNumber)  (init- or control-rate args only)

where the argument within the parentheses may be a further expression.

  Performance

octmidinn is a function that takes an i-rate or k-rate value
representing a Midi note number and returns the equivalent pitch value
in Csound's octave-point-decimal format. This conversion assumes that
Middle C (8.000 in oct) is Midi note number 60. Midi note number values
are typically integers in the range from 0 to 127 but fractional values
or values outside of this range will be interpreted consistently.

  octmidinn vs. octmidi

The octmidinn opcode may be used in any Csound instrument instance
whether it is activated from a Midi event, score event, line event, or
from another instrument. The input value for octmidinn might for example
come from a p-field in a textual score or it may have been retrieved
from the real-time Midi event that activated the current note using the
notnum opcode. You must specify an i-rate or k-rate expression for the
Midi note number that is to be converted. On the other hand, the octmidi
opcode only produces meaningful results in a Midi-activated note (either
real-time or from a Midi score with the -F flag). With octmidi, the Midi
note number value is taken from the Midi event associated with the
instrument instance, and no location or expression for this value may be
specified.

octmidinn and its related opcodes are really value converters with a
special function of manipulating pitch data.

Data concerning pitch and frequency can exist in any of the following
forms:

Table 17. Pitch and Frequency Values

Name    Abbreviation
octave point pitch-class (8ve.pc)       pch
octave point decimal    oct
cycles per second       cps
Midi note number (0-127)        midinn

The first two forms consist of a whole number, representing octave
registration, followed by a specially interpreted fractional part. For
pch, the fraction is read as two decimal digits representing the 12
equal-tempered pitch classes from .00 for C to .11 for B. For oct, the
fraction is interpreted as a true decimal fractional part of an octave.
The two fractional forms are thus related by the factor 100/12. In both
forms, the fraction is preceded by a whole number octave index such that
8.00 represents Middle C, 9.00 the C above, etc. Midi note number values
range between 0 and 127 (inclusively) with 60 representing Middle C, and
are usually whole numbers. Thus A440 can be represented alternatively by
440 (cps), 69 (midinn), 8.09 (pch), or 8.75 (oct). Microtonal divisions
of the pch semitone can be encoded by using more than two decimal places.

The mnemonics of the pitch conversion units are derived from morphemes
of the forms involved, the second morpheme describing the source and the
first morpheme the object (result). Thus cpspch(8.09) will convert the
pitch argument 8.09 to its cps (or Hertz) equivalent, giving the value
of 440. Since the argument is constant over the duration of the note,
this conversion will take place at i-time, before any samples for the
current note are produced.

By contrast, the conversion cpsoct(8.75 + k1) which gives the value of
A440 transposed by the octave interval k1. The calculation will be
repeated every k-period since that is the rate at which k1 varies.

  Note

The conversion from pch, oct, or midinn into cps is not a linear
operation but involves an exponential process that could be
time-consuming when executed repeatedly. Csound now uses a built-in
table lookup to do this efficiently, even at audio rates. Because the
table index is truncated without interpolation, pitch resolution when
using one of these opcodes is limited to 8192 discrete and equal
divisions of the octave, and some pitches of the standard 12-tone
equally-tempered scale are very slightly mistuned (by at most 0.15 cents).


===========================================================================
octpch                                                               *octpch*

  Description

Converts a pitch-class value to octave-point-decimal.

  Syntax

octpch (pch)  (init- or control-rate args only)

where the argument within the parentheses may be a further expression.

  Performance

octpch and its related opcodes are really value converters with a
special function of manipulating pitch data.

Data concerning pitch and frequency can exist in any of the following
forms:

Table 18. Pitch and Frequency Values

Name    Abbreviation
octave point pitch-class (8ve.pc)       pch
octave point decimal    oct
cycles per second       cps
Midi note number (0-127)        midinn

The first two forms consist of a whole number, representing octave
registration, followed by a specially interpreted fractional part. For
pch, the fraction is read as two decimal digits representing the 12
equal-tempered pitch classes from .00 for C to .11 for B. For oct, the
fraction is interpreted as a true decimal fractional part of an octave.
The two fractional forms are thus related by the factor 100/12. In both
forms, the fraction is preceded by a whole number octave index such that
8.00 represents Middle C, 9.00 the C above, etc. Midi note number values
range between 0 and 127 (inclusively) with 60 representing Middle C, and
are usually whole numbers. Thus A440 can be represented alternatively by
440 (cps), 69 (midinn), 8.09 (pch), or 8.75 (oct). Microtonal divisions
of the pch semitone can be encoded by using more than two decimal places.

The mnemonics of the pitch conversion units are derived from morphemes
of the forms involved, the second morpheme describing the source and the
first morpheme the object (result). Thus cpspch(8.09) will convert the
pitch argument 8.09 to its cps (or Hertz) equivalent, giving the value
of 440. Since the argument is constant over the duration of the note,
this conversion will take place at i-time, before any samples for the
current note are produced.

By contrast, the conversion cpsoct(8.75 + k1) which gives the value of
A440 transposed by the octave interval k1. The calculation will be
repeated every k-period since that is the rate at which k1 varies.

  Note

The conversion from pch, oct, or midinn into cps is not a linear
operation but involves an exponential process that could be
time-consuming when executed repeatedly. Csound now uses a built-in
table lookup to do this efficiently, even at audio rates. Because the
table index is truncated without interpolation, pitch resolution when
using one of these opcodes is limited to 8192 discrete and equal
divisions of the octave, and some pitches of the standard 12-tone
equally-tempered scale are very slightly mistuned (by at most 0.15 cents).


===========================================================================
olabuffer                                                         *olabuffer*

  Description

olabuffer This opcode takes 1 dimensional k-rate arrays that contain
sequential frames of audio and sums them based on an overlap factor
resulting in an audio signal output. This is useful for frame based
audio processing such as spectral analysis/synthesis.

  Syntax

aout olabuffer kin, ioverlap

  Initialization

ioverlap -- The amount of overlaps per k-array input frame sample size.
For example for an input window size of 1024, and a hop size of 256 the
overlap factor would be 4. The overlap factor must be larger than or
equal to ksmps and must also be an integer multiple of the input k-rate
array sample count.

  Performance

aout -- The resulting audio signal from the added input frames. kin -- A
k-rate array containing sequential frames of audio.


===========================================================================
opcode                                                               *opcode*

  Defining opcodes

The opcode and endop statements allow defining a new opcode that can be
used the same way as any of the built-in Csound opcodes. These opcode
blocks are very similar to instruments (and are, in fact, implemented as
special instruments), but cannot be called as a normal instrument e.g.
with the i statements.

A user-defined opcode block must precede the instrument (or other
opcode) from which it is used. But it is possible to call the opcode
from itself. This allows recursion of any depth that is limited only by
available memory. Additionally, there is an experimental feature that
allows running the opcode definition at a higher control rate than the
kr value specified in the orchestra header.

Similarly to instruments, the variables and labels of a user-defined
opcode block are local and cannot be accessed from the caller instrument
(and the opcode cannot access variables of the caller, either).

Some parameters are automatically copied at initialization, however:

  * all p-fields (including p1)

  * extra time (see also xtratim, linsegr, and related opcodes). This
    may affect the operation of linsegr/expsegr/linenr/envlpxr in the
    user-defined opcode block.

  * MIDI parameters, if there are any.

Also, the release flag (see the release opcode) is copied at performance
time.

Modifying the note duration in the opcode definition by assigning to p3,
or using ihold, turnoff, xtratim, linsegr, or similar opcodes will also
affect the caller instrument. Changes to MIDI controllers (for example
with ctrlinit) will also apply to the instrument from which the opcode
was called.

Use the setksmps opcode to set the local ksmps value.

The xin and xout opcodes copy variables to and from the opcode
definition, allowing communication with the calling instrument.

The types of input and output variables are defined by the parameters
intypes and outtypes.

  Tip

You can create UDOs which take no inputs or outputs by using 0 instead
of a string.

  Notes

  * xin and xout should be called only once, and xin should precede
    xout, otherwise an init error and deactivation of the current
    instrument may occur.

  * These opcodes actually run only at i-time. Performance time copying
    is done by the user opcode call. This means that skipping xin or
    xout with kgoto has no effect, while skipping with igoto affects
    both init and performance time operation.

  Syntax

opcode name, outtypes, intypes

  Initialization

name -- name of the opcode. It may consist of any combination of
letters, digits, and underscore but should not begin with a digit. If an
opcode with the specified name already exists, it is redefined (a
warning is printed in such cases). Some reserved words (like instr and
endin) cannot be redefined.

intypes -- list of input types, any combination of the characters: a, k,
O, P, V, K, i, o, p, and j. A single 0 character can be used if there
are no input arguments. Double quotes and delimiter characters (e.g.
comma) are not needed.

The meaning of the various intypes is shown in the following table:

Type    Description     Variable Types Allowed  Updated At
a       a-rate variable a-rate  a-rate
i       i-rate variable i-rate  i-time
j       optional i-time, defaults to -1 i-rate, constant        i-time
k       k-rate variable k- and i-rate, constant k-rate
O       optional k-rate variable, defaults to 0 k- and i-rate, constant k-rate
P       optional k-rate variable, defaults to 1 k- and i-rate, constant k-rate
V       optional k-rate variable, defaults to 0.5       k- and i-rate, constant k-rate
K       k-rate with initialization      k- and i-rate, constant i-time and k-rate
o       optional i-time, defaults to 0  i-rate, constant        i-time
p       optional i-time, defaults to 1  i-rate, constant        i-time
S       string variable i-rate string   i-time

The maximum allowed number of input arguments is 256.

outtypes -- list of output types. The format is the same as in the case
of intypes.

Here are the available outtypes:

Type    Description     Variable Types Allowed  Updated At
a       a-rate variable a-rate  a-rate
i       i-rate variable i-rate  i-time
k       k-rate variable k-rate  k-rate
K       k-rate with initialization      k-rate  i-time and k-rate

The maximum allowed number of output arguments is 256.

iksmps (optional, default=0) -- sets the local ksmps value. Must be a
positive integer, and also the ksmps of the calling instrument or opcode
must be an integer multiple of this value. For example, if ksmps is 10
in the instrument from which the opcode was called, the allowed values
for iksmps are 1, 2, 5, and 10.

If iksmps is set to zero, the ksmps of the caller instrument or opcode
is used (this is the default behavior).

  Note

The local ksmps is implemented by splitting up a control period into
smaller sub-kperiods and temporarily modifying internal Csound global
variables. This also requires converting the rate of k-rate input and
output arguments (input variables receive the same value in all
sub-kperiods, while outputs are written only in the last one).

  Warning about local ksmps

When the local ksmps is not the same as the orchestra level ksmps value
(as specified in the orchestra header), global a-rate operations must
not be used in the user-defined opcode block.

These include:

  * any access to “ga” variables

  * a-rate zak opcodes (zar, zaw, etc.)

  * tablera and tablewa (these two opcodes may in fact work, but caution
    is needed)

  * The in and out opcode family (these read from, and write to global
    a-rate buffers)

In general, the local ksmps should be used with care as it is an
experimental feature, although it works correctly in most cases.

The setksmps statement can be used to set the local ksmps value of the
user-defined opcode block. It has one i-time parameter specifying the
new ksmps value (which is left unchanged if zero is used, see also the
notes about iksmps above). setksmps should be used before any other
opcodes (but allowed after xin), otherwise unpredictable results may occur.

The input parameters can be read with xin, and the output is written by
xout opcode. Only one instance of these units should be used, as xout
overwrites and does not accumulate the output. The number and type of
arguments for xin and xout must be the same as in the declaration of the
user-defined opcode block (see tables above).

The input and output arguments must agree with the definition both in
number (except if the optional i-time input is used) and type. An
optional i-time input parameter (iksmps) is automatically added to the
intypes list, and (similarly to setksmps) sets the local ksmps value.

  Performance

The syntax of a user-defined opcode block is as follows:

opcode  name, outtypes, intypes
xinarg1 [, xinarg2] [, xinarg3] ... [xinargN]  xin
[setksmps  iksmps]
... the rest of the instrument's code.
xout  xoutarg1 [, xoutarg2] [, xoutarg3] ... [xoutargN]
endop

The new opcode can then be used with the usual syntax:

  [xoutarg1] [, xoutarg2] ... [xoutargN] name  [xinarg1] [, xinarg2] ... [xinargN] [, iksmps]

  Note

The opcode call is always executed both at initialization and
performance time, even if there are no a- or k-rate arguments. If there
are many user opcode calls that are known to have no effect at
performance time in an instrument, then it may save some CPU time to
jump over groups of such opcodes with kgoto.


===========================================================================
oscbnk                                                               *oscbnk*

  Description

This unit generator mixes the output of any number of oscillators. The
frequency, phase, and amplitude of each oscillator can be modulated by
two LFOs (all oscillators have a separate set of LFOs, with different
phase and frequency); additionally, the output of each oscillator can be
filtered through an optional parametric equalizer (also controlled by
the LFOs). This opcode is most useful for rendering ensemble (strings,
choir, etc.) instruments.

Although the LFOs run at k-rate, amplitude, phase and filter modulation
are interpolated internally, so it is possible (and recommended in most
cases) to use this unit at low (˜1000 Hz) control rates without audible
quality degradation.

The start phase and frequency of all oscillators and LFOs can be set by
a built-in seedable 31-bit random number generator, or specified
manually in a function table (GEN2).

  Syntax

ares oscbnk  kcps, kamd, kfmd, kpmd, iovrlap, iseed, kl1minf, kl1maxf, \
      kl2minf, kl2maxf, ilfomode, keqminf, keqmaxf, keqminl, keqmaxl, \
      keqminq, keqmaxq, ieqmode, kfn [, il1fn] [, il2fn] [, ieqffn]   \
      [, ieqlfn] [, ieqqfn] [, itabl] [, ioutfn]

  Initialization

iovrlap -- Number of oscillator units.

iseed -- Seed value for random number generator (positive integer in the
range 1 to 2147483646 (2 ^ 31 - 2)). iseed <= 0 seeds from the current
time.

ieqmode -- Parametric equalizer mode

  * -1: disable EQ (faster)

  * 0: peak

  * 1: low shelf

  * 2: high shelf

  * 3: peak (filter interpolation disabled)

  * 4: low shelf (interpolation disabled)

  * 5: high shelf (interpolation disabled)

The non-interpolated modes are faster, and in some cases (e.g. high
shelf filter at low cutoff frequencies) also more stable; however,
interpolation is useful for avoiding “zipper noise” at low control rates.

ilfomode -- LFO modulation mode, sum of:

  * 128: LFO1 to frequency

  * 64: LFO1 to amplitude

  * 32: LFO1 to phase

  * 16: LFO1 to EQ

  * 8: LFO2 to frequency

  * 4: LFO2 to amplitude

  * 2: LFO2 to phase

  * 1: LFO2 to EQ

If an LFO does not modulate anything, it is not calculated, and the
ftable number (il1fn or il2fn) can be omitted.

il1fn (optional: default=0) -- LFO1 function table number. The waveform
in this table has to be normalized (absolute value <= 1), and is read
with linear interpolation.

il2fn (optional: default=0) -- LFO2 function table number. The waveform
in this table has to be normalized, and is read with linear interpolation.

ieqffn, ieqlfn, ieqqfn (optional: default=0) -- Lookup tables for EQ
frequency, level, and Q (optional if EQ is disabled). Table read
position is 0 if the modulator signal is less than, or equal to -1,
(table length / 2) if the modulator signal is zero, and the guard point
if the modulator signal is greater than, or equal to 1. These tables
have to be normalized to the range 0 - 1, and have an extended guard
point (table length = power of two + 1). All tables are read with linear
interpolation.

itabl (optional: default=0) -- Function table storing phase and
frequency values for all oscillators (optional). The values in this
table are in the following order (5 for each oscillator unit):

oscillator phase, lfo1 phase, lfo1 frequency, lfo2 phase, lfo2 frequency, ...

All values are in the range 0 to 1; if the specified number is greater
than 1, it is wrapped (phase) or limited (frequency) to the allowed
range. A negative value (or end of table) will use the output of the
random number generator. The random seed is always updated (even if no
random number was used), so switching one value between random and fixed
will not change others.

ioutfn (optional: default=0) -- Function table to write phase and
frequency values (optional). The format is the same as in the case of
itabl. This table is useful when experimenting with random numbers to
record the best values.

The two optional tables (itabl and ioutfn) are accessed only at i-time.
This is useful to know, as the tables can be safely overwritten after
opcode initialization, which allows precalculating parameters at i-time
and storing in a temporary table before oscbnk initialization.

  Performance

ares -- Output signal.

kcps -- Oscillator frequency in Hz.

kamd -- AM depth (0 - 1).

(AM output) = (AM input) * ((1 - (AM depth)) + (AM depth) * (modulator))

If ilfomode isn't set to modulate the amplitude, then (AM output) = (AM
input) regardless of the value of kamd. That means that kamd will have
no effect.

Note: Amplitude modulation is applied before the parametric equalizer.

kfmd -- FM depth (in Hz).

kpmd -- Phase modulation depth.

kl1minf, kl1maxf -- LFO1 minimum and maximum frequency in Hz.

kl2minf, kl2maxf -- LFO2 minimum and maximum frequency in Hz. (Note:
oscillator and LFO frequencies are allowed to be zero or negative.)

keqminf, keqmaxf -- Parametric equalizer minimum and maximum frequency
in Hz.

keqminl, keqmaxl -- Parametric equalizer minimum and maximum level.

keqminq, keqmaxq -- Parametric equalizer minimum and maximum Q.

kfn -- Oscillator waveform table. Table number can be changed at k-rate
(this is useful to select from a set of band-limited tables generated by
GEN30, to avoid aliasing). The table is read with linear interpolation.

  Note

oscbnk uses the same random number generator as rnd31. So reading its
documentation is also recommended.


===========================================================================
oscil1                                                               *oscil1*

  Description

Accesses table values by incremental sampling.

  Syntax

kres oscil1 idel, kamp, idur [, ifn]

  Initialization

idel -- delay in seconds before oscil1 incremental sampling begins.

idur -- duration in seconds to sample through the oscil1 table just
once. A zero or negative value will cause all initialization to be skipped.

ifn -- (optional) function table number. tablei, oscil1i require the
extended guard point. The number defaults to -1 which indicates a sinewave.

  Performance

kamp -- amplitude factor.

oscil1 accesses values by sampling once through the function table at a
rate determined by idur. For the first idel seconds, the point of scan
will reside at the first location of the table; it will then begin
moving through the table at a constant rate, reaching the end in another
idur seconds; from that time on (i.e. after idel + idur seconds) it will
remain pointing at the last location. Each value obtained from sampling
is then multiplied by an amplitude factor kamp before being written into
the result.


===========================================================================
oscil1i                                                             *oscil1i*

  Description

Accesses table values by incremental sampling with linear interpolation.

  Syntax

kres oscil1i idel, kamp, idur [, ifn]

  Initialization

idel -- delay in seconds before oscil1i incremental sampling begins.

idur -- duration in seconds to sample through the oscil1i table just
once. A zero or negative value will cause all initialization to be skipped.

ifn -- (optional) function table number. oscil1i requires the extended
guard point. The default value is -1 indicating a sine wave.

  Performance

kamp -- amplitude factor

oscil1i is an interpolating unit in which the fractional part of index
is used to interpolate between adjacent table entries. The smoothness
gained by interpolation is at some small cost in execution time (see
also oscili, etc.), but the interpolating and non-interpolating units
are otherwise interchangeable.


===========================================================================
oscil3                                                               *oscil3*

  Description

oscil3 reads table ifn sequentially and repeatedly at a frequency xcps.
The amplitude is scaled by xamp. Cubic interpolation is applied for
table look up from internal phase values.

  Syntax

ares oscil3 xamp, xcps [, ifn, iphs]

kres oscil3 kamp, kcps [, ifn, iphs]

  Initialization

ifn (optional) -- function table number. Requires a wrap-around guard
point. Defaults to -1 indicating a sinewave.

iphs (optional) -- initial phase of sampling, expressed as a fraction of
a cycle (0 to 1). A negative value will cause phase initialization to be
skipped. The default value is 0.

  Performance

kamp, xamp -- amplitude

kcps, xcps -- frequency in cycles per second.

oscil3 is identical to oscili, except that it uses cubic interpolation.

Table ifn is incrementally sampled modulo the table length and the value
obtained is multiplied by amp.

If you need to change the oscillator table with a k-rate signal, you can
use oscilikt.


===========================================================================
oscil                                                                 *oscil*

  Description

oscil reads table ifn sequentially and repeatedly at a frequency xcps.
The amplitude is scaled by xamp.

  Syntax

ares oscil xamp, xcps [, ifn, iphs]

kres oscil kamp, kcps [, ifn, iphs]

  Initialization

ifn -- (optional) function table number. Requires a wrap-around guard
point. The table number defaults to -1 which indicates a sinewave.

iphs (optional, default=0) -- initial phase of sampling, expressed as a
fraction of a cycle (0 to 1). A negative value will cause phase
initialization to be skipped. The default value is 0.

  Performance

kamp, xamp -- amplitude

kcps, xcps -- frequency in cycles per second.

The oscil opcode generates periodic control (or audio) signals
consisting of the value of kamp (xamp) times the value returned from
control rate (audio rate) sampling of a stored function table. The
internal phase is simultaneously advanced in accordance with the kcps or
xcps input value.

Table ifn is incrementally sampled modulo the table length and the value
obtained is multiplied by amp.

If you need to change the oscillator table with a k-rate signal, you can
use oscilikt.


===========================================================================
oscili                                                               *oscili*

  Description

oscili reads table ifn sequentially and repeatedly at a frequency xcps.
The amplitude is scaled by xamp. Linear interpolation is applied for
table look up from internal phase values.

  Syntax

ares oscili xamp, xcps[, ifn, iphs]

kres oscili kamp, kcps[, ifn, iphs]

  Initialization

ifn(optional) -- function table number. Requires a wrap-around guard
point. The table number defaults to -1 which indicates a sine wave.

iphs (optional) -- initial phase of sampling, expressed as a fraction of
a cycle (0 to 1). A negative value will cause phase initialization to be
skipped. The default value is 0.

  Performance

kamp, xamp -- amplitude

kcps, xcps -- frequency in cycles per second.

oscili differs from oscil in that the standard procedure of using a
truncated phase as a sampling index is here replaced by a process that
interpolates between two successive lookups. Interpolating generators
will produce a noticeably cleaner output signal, but they may take as
much as twice as long to run. Adequate accuracy can also be gained
without the time cost of interpolation by using large stored function
tables of 2K, 4K or 8K points if the space is available.

Table ifn is incrementally sampled modulo the table length and the value
obtained is multiplied by amp.

If you need to change the oscillator table with a k-rate signal, you can
use oscilikt.


===========================================================================
oscilikt                                                           *oscilikt*

  Description

oscilikt is very similar to oscili, but allows changing the table number
at k-rate. It is slightly slower than oscili (especially with high
control rate), although also more accurate as it uses a 31-bit phase
accumulator, as opposed to the 24-bit one used by oscili.

  Syntax

ares oscilikt xamp, xcps, kfn [, iphs] [, istor]

kres oscilikt kamp, kcps, kfn [, iphs] [, istor]

  Initialization

iphs (optional, defaults to 0) -- initial phase in the range 0 to 1.
Other values are wrapped to the allowed range.

istor (optional, defaults to 0) -- skip initialization.

  Performance

kamp, xamp -- amplitude.

kcps, xcps -- frequency in Hz. Zero and negative values are allowed.
However, the absolute value must be less than sr (and recommended to be
less than sr/2).

kfn -- function table number. Can be varied at control rate (useful to
“morph” waveforms, or select from a set of band-limited tables generated
by GEN30).


===========================================================================
osciliktp                                                         *osciliktp*

  Description

osciliktp allows phase modulation (which is actually implemented as
k-rate frequency modulation, by differentiating phase input). The
disadvantage is that there is no amplitude control, and frequency can be
varied only at the control-rate. This opcode can be faster or slower
than oscilikt, depending on the control-rate.

  Syntax

ares osciliktp kcps, kfn, kphs [, istor]

  Initialization

istor (optional, defaults to 0) -- Skips initialization.

  Performance

ares -- audio-rate ouptut signal.

kcps -- frequency in Hz. Zero and negative values are allowed. However,
the absolute value must be less than sr (and recommended to be less than
sr/2).

kfn -- function table number. Can be varied at control rate (useful to
“morph” waveforms, or select from a set of band-limited tables generated
by GEN30).

kphs -- phase (k-rate), the expected range is 0 to 1. The absolute value
of the difference of the current and previous value of kphs must be less
than ksmps.


===========================================================================
oscilikts                                                         *oscilikts*

  Description

oscilikts is the same as oscilikt. Except it has a sync input that can
be used to re-initialize the oscillator to a k-rate phase value. It is
slower than oscilikt and osciliktp.

  Syntax

ares oscilikts xamp, xcps, kfn, async, kphs [, istor]

  Initialization

istor (optional, defaults to 0) -- skip initialization.

  Performance

xamp -- amplitude.

xcps -- frequency in Hz. Zero and negative values are allowed. However,
the absolute value must be less than sr (and recommended to be less than
sr/2).

kfn -- function table number. Can be varied at control rate (useful to
“morph” waveforms, or select from a set of band-limited tables generated
by GEN30).

async -- any positive value resets the phase of oscilikts to kphs. Zero
or negative values have no effect.

kphs -- sets the phase, initially and when it is re-initialized with async.


===========================================================================
osciln                                                               *osciln*

  Description

Accesses table values at a user-defined frequency. This opcode can also
be written as oscilx.

  Syntax

ares osciln kamp, ifrq, ifn, itimes

  Initialization

ifrq, itimes -- rate and number of times through the stored table.

ifn -- function table number.

  Performance

kamp -- amplitude factor

osciln will sample several times through the stored table at a rate of
ifrq times per second, after which it will output zeros. Generates audio
signals only, with output values scaled by kamp.


===========================================================================
oscils                                                               *oscils*

  Description

Simple, fast sine oscillator, that uses only one multiply, and two add
operations to generate one sample of output, and does not require a
function table.

  Syntax

ares oscils iamp, icps, iphs [, iflg]

  Initialization

iamp -- output amplitude.

icps -- frequency in Hz (may be zero or negative, however the absolute
value must be less than sr/2).

iphs -- start phase between 0 and 1.

iflg -- sum of the following values:

  * 2: use double precision even if Csound was compiled to use floats.
    This improves quality (especially in the case of long performance
    time), but may be up to twice as slow.

  * 1: skip initialization.

  Performance

ares -- audio output


===========================================================================
oscilx                                                               *oscilx*

  Description

Same as the osciln opcode.

===========================================================================
OSCinit                                                             *OSCinit*

  Description

Starts a listening process, which can be used by OSClisten.

  Syntax

ihandle OSCinit iport

  Initialization

ihandle -- handle returned that can be passed to any number of OSClisten
opcodes to receive messages on this port.

iport -- the port on which to listen.

  Performance

The listener runs in the background. See OSClisten for details.


===========================================================================
OSClisten                                                         *OSClisten*

  Description

On each k-cycle looks to see if an OSC message has been send to a given
path of a given type.

  Syntax

kans OSClisten ihandle, idest, itype [, xdata1, xdata2, ...]

  Initialization

ihandle -- a handle returned by an earlier call to OSCinit, to associate
OSClisten with a particular port number.

idest -- a string that is the destination address. This takes the form
of a file name with directories. Csound uses this address to decide if
messages are meant for csound.

itype -- a string that indicates the types of the optional arguments
that are to be read. The string can contain the characters "acdfhisAG"
which stand for audio, character, double, float, 64-bit integer, 32-bit
integer, string, scalar array and f-table. All types other than 'asA'
require a k-rate variable; 's' requires a string variable, 'a' an audio
variable and 'A' an i- or k- rate array. Fot type 'G' a variable or
constant can be used.

A handler is inserted into the listener (see OSCinit) to intercept
messages of this pattern.

  Performance

kans -- set to 1 if a new message was received, or zero if not. If
multiple messages are received in a single control period, the messages
are buffered, and OSClisten can be called again until zero is returned.

If there was a message the xdata variables are set to the incoming
values, as interpretted by the itype parameter. Note that although the
xdata variables are on the right of an operation they are actually
outputs, and so must be variables of type a, ga, k, gk, S, gS, k[] and
gk[] and may need to be declared with init, or = in the case of string
variables, before calling OSClisten.


===========================================================================
OSCsend                                                             *OSCsend*

  Description

Uses the OSC protocol to send message to other OSC listening processes.

  Syntax

OSCsend kwhen, ihost, iport, idestination, itype [, xdata1, xdata2, ...]

  Initialization

ihost -- a string that is the intended host computer domain name. An
empty string is interpreted as the current computer.

iport -- the number of the port that is used for the communication.

idest -- a string that is the destination address. This takes the form
of a file name with directories. Csound just passes this string to the
raw sending code and makes no interpretation.

itype -- a string that indicates the types of the optional arguments
that are read at k-rate. The string can contain the characters
"abcdfilmstAG" which stand for audio, Boolean, character, double, float,
32-bit integer, 64-bit integer, MIDI, string, timestamp, k-rate array
and ftable.

  Performance

kwhen -- a message is sent whenever this value changes. A message will
always be sent on the first call.

The data is taken from the k-values or a-value that follow the format
string. In a similar way to a printf format, the characters in order
determine how the argument is interpreted. Note that a time stamp takes
two arguments.


===========================================================================
out32                                                                 *out32*

  Description

Writes 32-channel audio data to an external device or stream.

  Syntax

out32 asig1, asig2, asig3, asig4, asig5, asig6, asig7, asig8, asig10, \
      asig11, asig12, asig13, asig14, asig15, asig16, asig17, asig18, \
      asig19, asig20, asig21, asig22, asig23, asig24, asig25, asig26, \
      asig27, asig28, asig29, asig30, asig31, asig32

  Performance

out32 outputs 32 channels of audio.


===========================================================================
out                                                                     *out*

  Description

Writes audio data to an external device or stream, either from audio
variables or from an audio array.

  Syntax

out asig1[, asig2,....]

out aarray

  Performance

Sends audio samples to an accumulating output buffer (created at the
beginning of performance) which serves to collect the output of all
active instruments before the sound is written to disk. There can be any
number of these output units in an instrument.

The type (mono, stereo, quad, hex, or oct) should agree with nchnls. But
as of version 3.50, Csound will attempt to change an incorrect opcode to
agree with nchnls statement.


===========================================================================
outc                                                                   *outc*

  Description

Writes audio data with an arbitrary number of channels to an external
device or stream.

  Syntax

outc asig1 [, asig2] [...]

  Performance

outc outputs as many channels as provided. Any channels greater than
nchnls are ignored. Zeros are added as necessary


===========================================================================
outch                                                                 *outch*

  Description

Writes multi-channel audio data, with user-controllable channels, to an
external device or stream.

  Syntax

outch kchan1, asig1 [, kchan2] [, asig2] [...]

  Performance

outch outputs asig1 on the channel determined by kchan1, asig2 on the
channel determined by kchan2, etc.

  Note

The highest number for kchanX available for use with outch depends on
nchnls. If kchanX is greater than nchnls, asigX will be silent. Note
that outch will give a warning but not an error in this case.


===========================================================================
outh                                                                   *outh*

  Description

Writes 6-channel audio data to an external device or stream.

  Syntax

outh asig1, asig2, asig3, asig4, asig5, asig6

  Performance

Sends 6-channel audio samples to an accumulating output buffer (created
at the beginning of performance) which serves to collect the output of
all active instruments before the sound is written to disk. There can be
any number of these output units in an instrument.

The type (mono, stereo, quad, hex, or oct) should agree with nchnls. But
as of version 3.50, Csound will attempt to change an incorrect opcode to
agree with nchnls statement.


===========================================================================
outiat                                                               *outiat*

  Description

Sends MIDI aftertouch messages at i-rate.

  Syntax

outiat ichn, ivalue, imin, imax

  Initialization

ichn -- MIDI channel number (1-16)

ivalue -- floating point value

imin -- minimum floating point value (converted in MIDI integer value 0)

imax -- maximum floating point value (converted in MIDI integer value
127 (7 bit))

  Performance

outiat (i-rate aftertouch output) sends aftertouch messages. It works
only with MIDI instruments which recognize them. It can drive a
different value of a parameter for each note currently active.

It can scale an i-value floating-point argument according to the imin
and imax values. For example, set imin = 1.0 and imax = 2.0. When the
ivalue argument receives a 2.0 value, the opcode will send a 127 value
to the MIDI OUT device. When the ivalue argument receives a 1.0 value,
it will send a 0 value. i-rate opcodes send their message once during
instrument initialization.


===========================================================================
outic14                                                             *outic14*

  Description

Sends 14-bit MIDI controller output at i-rate.

  Syntax

outic14 ichn, imsb, ilsb, ivalue, imin, imax

  Initialization

ichn -- MIDI channel number (1-16)

imsb -- most significant byte controller number when using 14-bit
parameters (0-127)

ilsb -- least significant byte controller number when using 14-bit
parameters (0-127)

ivalue -- floating point value

imin -- minimum floating point value (converted in MIDI integer value 0)

imax -- maximum floating point value (converted in MIDI integer value
16383 (14-bit))

  Performance

outic14 (i-rate MIDI 14-bit controller output) sends a pair of
controller messages. This opcode can drive 14-bit parameters on MIDI
instruments that recognize them. The first control message contains the
most significant byte of ivalue argument while the second message
contains the less significant byte. imsb and ilsb are the number of the
most and less significant controller.

This opcode can drive a different value of a parameter for each note
currently active.

It can scale an i-value floating-point argument according to the imin
and imax values. For example, set imin = 1.0 and imax = 2.0. When the
ivalue argument receives a 2.0 value, the opcode will send a 127 value
to the MIDI OUT device. When the ivalue argument receives a 1.0 value,
it will send a 0 value. i-rate opcodes send their message once during
instrument initialization.


===========================================================================
outic                                                                 *outic*

  Description

Sends MIDI controller output at i-rate.

  Syntax

outic ichn, inum, ivalue, imin, imax

  Initialization

ichn -- MIDI channel number (1-16)

inum -- controller number (0-127 for example 1 = ModWheel; 2 =
BreathControl etc.)

ivalue -- floating point value

imin -- minimum floating point value (converted in MIDI integer value 0)

imax -- maximum floating point value (converted in MIDI integer value
127 (7 bit))

  Performance

outic (i-rate MIDI controller output) sends controller messages to the
MIDI OUT device. It works only with MIDI instruments which recognize
them. It can drive a different value of a parameter for each note
currently active.

It can scale an i-value floating-point argument according to the imin
and imax values. For example, set imin = 1.0 and imax = 2.0. When the
ivalue argument receives a 2.0 value, the opcode will send a 127 value
to the MIDI OUT device. When the ivalue argument receives a 1.0 value,
it will send a 0 value. i-rate opcodes send their message once during
instrument initialization.


===========================================================================
outipat                                                             *outipat*

  Description

Sends polyphonic MIDI aftertouch messages at i-rate.

  Syntax

outipat ichn, inotenum, ivalue, imin, imax

  Initialization

ichn -- MIDI channel number (1-16)

inotenum -- MIDI note number (used in polyphonic aftertouch messages)

ivalue -- floating point value

imin -- minimum floating point value (converted in MIDI integer value 0)

imax -- maximum floating point value (converted in MIDI integer value
127 (7 bit))

  Performance

outipat (i-rate polyphonic aftertouch output) sends polyphonic
aftertouch messages. It works only with MIDI instruments which recognize
them. It can drive a different value of a parameter for each note
currently active.

It can scale an i-value floating-point argument according to the imin
and imax values. For example, set imin = 1.0 and imax = 2.0. When the
ivalue argument receives a 2.0 value, the opcode will send a 127 value
to the MIDI OUT device. When the ivalue argument receives a 1.0 value,
it will send a 0 value. i-rate opcodes send their message once during
instrument initialization.


===========================================================================
outipb                                                               *outipb*

  Description

Sends MIDI pitch-bend messages at i-rate.

  Syntax

outipb ichn, ivalue, imin, imax

  Initialization

ichn -- MIDI channel number (1-16)

ivalue -- floating point value

imin -- minimum floating point value (converted in MIDI integer value 0)

imax -- maximum floating point value (converted in MIDI integer value
127 (7 bit))

  Performance

outipb (i-rate pitch bend output) sends pitch bend messages. It works
only with MIDI instruments which recognize them. It can drive a
different value of a parameter for each note currently active.

It can scale an i-value floating-point argument according to the imin
and imax values. For example, set imin = 1.0 and imax = 2.0. When the
ivalue argument receives a 2.0 value, the opcode will send a 127 value
to the MIDI OUT device. When the ivalue argument receives a 1.0 value,
it will send a 0 value. i-rate opcodes send their message once during
instrument initialization.


===========================================================================
outipc                                                               *outipc*

  Description

Sends MIDI program change messages at i-rate

  Syntax

outipc ichn, iprog, imin, imax

  Initialization

ichn -- MIDI channel number (1-16)

iprog -- program change number in floating point

imin -- minimum floating point value (converted in MIDI integer value 0)

imax -- maximum floating point value (converted in MIDI integer value
127 (7 bit))

  Performance

outipc (i-rate program change output) sends program change messages. It
works only with MIDI instruments which recognize them. It can drive a
different value of a parameter for each note currently active.

It can scale an i-value floating-point argument according to the imin
and imax values. For example, set imin = 1.0 and imax = 2.0. When the
ivalue argument receives a 2.0 value, the opcode will send a 127 value
to the MIDI OUT device. When the ivalue argument receives a 1.0 value,
it will send a 0 value. i-rate opcodes send their message once during
instrument initialization.


===========================================================================
outkat                                                               *outkat*

  Description

Sends MIDI aftertouch messages at k-rate.

  Syntax

outkat kchn, kvalue, kmin, kmax

  Performance

kchn -- MIDI channel number (1-16)

kvalue -- floating point value

kmin -- minimum floating point value (converted in MIDI integer value 0)

kmax -- maximum floating point value (converted in MIDI integer value 127)

outkat (k-rate aftertouch output) sends aftertouch messages. It works
only with MIDI instruments which recognize them. It can drive a
different value of a parameter for each note currently active.

It can scale the k-value floating-point argument according to the kmin
and kmax values. For example: set kmin = 1.0 and kmax = 2.0. When the
kvalue argument receives a 2.0 value, the opcode will send a 127 value
to the MIDI OUT device. When the kvalue argument receives a 1.0 value,
it will send a 0 value. k-rate opcodes send a message each time the MIDI
converted value of argument kvalue changes.


===========================================================================
outkc14                                                             *outkc14*

  Description

Sends 14-bit MIDI controller output at k-rate.

  Syntax

outkc14 kchn, kmsb, klsb, kvalue, kmin, kmax

  Performance

kchn -- MIDI channel number (1-16)

kmsb -- most significant byte controller number when using 14-bit
parameters (0-127)

klsb -- least significant byte controller number when using 14-bit
parameters (0-127)

kvalue -- floating point value

kmin -- minimum floating point value (converted in MIDI integer value 0)

kmax -- maximum floating point value (converted in MIDI integer value
16383 (14-bit))

outkc14 (k-rate MIDI 14-bit controller output) sends a pair of
controller messages. It works only with MIDI instruments which recognize
them. These opcodes can drive 14-bit parameters on MIDI instruments that
recognize them. The first control message contains the most significant
byte of kvalue argument while the second message contains the less
significant byte. kmsb and klsb are the number of the most and less
significant controller.

It can drive a different value of a parameter for each note currently
active.

It can scale the k-value floating-point argument according to the kmin
and kmax values. For example: set kmin = 1.0 and kmax = 2.0. When the
kvalue argument receives a 2.0 value, the opcode will send a 127 value
to the MIDI OUT device. When the kvalue argument receives a 1.0 value,
it will send a 0 value. k-rate opcodes send a message each time the MIDI
converted value of argument kvalue changes.


===========================================================================
outkc                                                                 *outkc*

  Description

Sends MIDI controller messages at k-rate.

  Syntax

outkc kchn, knum, kvalue, kmin, kmax

  Performance

kchn -- MIDI channel number (1-16)

knum -- controller number (0-127 for example 1 = ModWheel; 2 =
BreathControl etc.)

kvalue -- floating point value

kmin -- minimum floating point value (converted in MIDI integer value 0)

kmax -- maximum floating point value (converted in MIDI integer value
127 (7 bit))

outkc (k-rate MIDI controller output) sends controller messages to MIDI
OUT device. It works only with MIDI instruments which recognize them. It
can drive a different value of a parameter for each note currently active.

It can scale the k-value floating-point argument according to the kmin
and kmax values. For example: set kmin = 1.0 and kmax = 2.0. When the
kvalue argument receives a 2.0 value, the opcode will send a 127 value
to the MIDI OUT device. When the kvalue argument receives a 1.0 value,
it will send a 0 value. k-rate opcodes send a message each time the MIDI
converted value of argument kvalue changes.


===========================================================================
outkpat                                                             *outkpat*

  Description

Sends polyphonic MIDI aftertouch messages at k-rate.

  Syntax

outkpat kchn, knotenum, kvalue, kmin, kmax

  Performance

kchn -- MIDI channel number (1-16)

knotenum -- MIDI note number (used in polyphonic aftertouch messages)

kvalue -- floating point value

kmin -- minimum floating point value (converted in MIDI integer value 0)

kmax -- maximum floating point value (converted in MIDI integer value
127 (7 bit))

outkpat (k-rate polyphonic aftertouch output) sends polyphonic
aftertouch messages. It works only with MIDI instruments which recognize
them. It can drive a different value of a parameter for each note
currently active.

It can scale the k-value floating-point argument according to the kmin
and kmax values. For example: set kmin = 1.0 and kmax = 2.0. When the
kvalue argument receives a 2.0 value, the opcode will send a 127 value
to the MIDI OUT device. When the kvalue argument receives a 1.0 value,
it will send a 0 value. k-rate opcodes send a message each time the MIDI
converted value of argument kvalue changes.


===========================================================================
outkpb                                                               *outkpb*

  Description

Sends MIDI pitch-bend messages at k-rate.

  Syntax

outkpb kchn, kvalue, kmin, kmax

  Performance

kchn -- MIDI channel number (1-16)

kvalue -- floating point value

kmin -- minimum floating point value (converted in MIDI integer value 0)

kmax -- maximum floating point value (converted in MIDI integer value
127 (7 bit))

outkpb (k-rate pitch-bend output) sends pitch-bend messages. It works
only with MIDI instruments which recognize them. It can drive a
different value of a parameter for each note currently active.

It can scale the k-value floating-point argument according to the kmin
and kmax values. For example: set kmin = 1.0 and kmax = 2.0. When the
kvalue argument receives a 2.0 value, the opcode will send a 127 value
to the MIDI OUT device. When the kvalue argument receives a 1.0 value,
it will send a 0 value. k-rate opcodes send a message each time the MIDI
converted value of argument kvalue changes.


===========================================================================
outkpc                                                               *outkpc*

  Description

Sends MIDI program change messages at k-rate.

  Syntax

outkpc kchn, kprog, kmin, kmax

  Performance

kchn -- MIDI channel number (1-16)

kprog -- program change number in floating point

kmin -- minimum floating point value (converted in MIDI integer value 0)

kmax -- maximum floating point value (converted in MIDI integer value
127 (7 bit))

outkpc (k-rate program change output) sends program change messages. It
works only with MIDI instruments which recognize them. These opcodes can
drive a different value of a parameter for each note currently active.

It can scale the k-value floating-point argument according to the kmin
and kmax values. For example: set kmin = 1.0 and kmax = 2.0. When the
kvalue argument receives a 2.0 value, the opcode will send a 127 value
to the MIDI OUT device. When the kvalue argument receives a 1.0 value,
it will send a 0 value. k-rate opcodes send a message each time the MIDI
converted value of argument kvalue changes.


===========================================================================
outleta                                                             *outleta*

  Description

Sends an arate signal out from an instrument to a named port.

  Syntax

outleta Sname, asignal

  Initialization

Sname -- String name of the outlet port. The name of the outlet is
implicitly qualified by the instrument name or number, so it is valid to
use the same outlet name in more than one instrument (but not to use the
same outlet name twice in one instrument).

  Performance

asignal -- audio output signal

During performance, the audio output signal is sent to each instance of
an instrument containing an inlet port to which this outlet has been
connected using the connect opcode. The signals of all the outlets
connected to an inlet are summed in the inlet.


===========================================================================
outletf                                                             *outletf*

  Description

Sends a frate signal (fsig) out from an instrument to a named port.

  Syntax

outletf Sname, fsignal

  Initialization

Sname -- String name of the outlet port. The name of the outlet is
implicitly qualified by the instrument name or number, so it is valid to
use the same outlet name in more than one instrument (but not to use the
same outlet name twice in one instrument).

  Performance

fsignal -- frate output signal (fsig)

During performance, the output signal is sent to each instance of an
instrument containing an inlet port to which this outlet has been
connected using the connect opcode. The signals of all the outlets
connected to an inlet are combined in the inlet.


===========================================================================
outletk                                                             *outletk*

  Description

Sends a krate signal out from an instrument to a named port.

  Syntax

outletk Sname, ksignal

  Initialization

Sname -- String name of the outlet port. The name of the outlet is
implicitly qualified by the instrument name or number, so it is valid to
use the same outlet name in more than one instrument (but not to use the
same outlet name twice in one instrument).

  Performance

ksignal -- krate output signal

During performance, the krate output signal is sent to each instance of
an instrument containing an inlet port to which this outlet has been
connected using the connect opcode. The signals of all the outlets
connected to an inlet are summed in the inlet.


===========================================================================
outletkid                                                         *outletkid*

  Description

Sends a krate signal out from an instrument to a named port.

  Syntax

outletkid Sname, SinstanceID, ksignal

  Initialization

Sname -- String name of the outlet port. The name of the outlet is
implicitly qualified by the instrument name or number, so it is valid to
use the same outlet name in more than one instrument (but not to use the
same outlet name twice in one instrument).

SinstanceID -- String name of the outlet port's instance ID. This
enables the inlet to discriminate between different instances of the
outlet, e,g. one instance of the outlet might be created by a note
specifying one instance ID, and another instance might be created by a
note specifying another ID. This might be used, e.g., to situate
difference instances of an instrument at different points in an
Ambisonic space in a spatializing effects processor.

  Performance

ksignal -- krate output signal

During performance, the krate output signal is sent to each instance of
an instrument containing an inlet port to which this outlet has been
connected using the connect opcode. The signals of all the outlets
connected to an inlet, but only those that have a matching instance ID,
are summed in the inlet.


===========================================================================
outletv                                                             *outletv*

  Description

Sends an arate array signal out from an instrument to a named port.

  Syntax

outletv Sname, array

  Initialization

Sname -- String name of the outlet port. The name of the outlet is
implicitly qualified by the instrument name or number, so it is valid to
use the same outlet name in more than one instrument (but not to use the
same outlet name twice in one instrument).

  Performance

array -- arate array output signal

During performance, the arate array output signal is sent to each
instance of an instrument containing an inlet port to which this outlet
has been connected using the connect opcode. The signals of all the
outlets connected to an inlet are summed in the inlet. The ports may
have any number of channels, but the inlet port must have the same
number of channels as the connected outlet ports.


===========================================================================
outo                                                                   *outo*

  Description

Writes 8-channel audio data to an external device or stream.

  Syntax

outo asig1, asig2, asig3, asig4, asig5, asig6, asig7, asig8

  Performance

Sends 8-channel audio samples to an accumulating output buffer (created
at the beginning of performance) which serves to collect the output of
all active instruments before the sound is written to disk. There can be
any number of these output units in an instrument.

The type (mono, stereo, quad, hex, or oct) should agree with nchnls. But
as of version 3.50, Csound will attempt to change an incorrect opcode to
agree with nchnls statement.


===========================================================================
outq1                                                                 *outq1*

  Description

Writes samples to quad channel 1 of an external device or stream.

  Syntax

outq1 asig

  Performance

Sends audio samples to an accumulating output buffer (created at the
beginning of performance) which serves to collect the output of all
active instruments before the sound is written to disk. There can be any
number of these output units in an instrument.

The type (mono, stereo, quad, hex, or oct) should agree with nchnls. But
as of version 3.50, Csound will attempt to change an incorrect opcode to
agree with the nchnls statement. Opcodes can be chosen to direct sound
to any particular channel: outs1 sends to stereo channel 1, outq3 to
quad channel 3, etc.


===========================================================================
outq2                                                                 *outq2*

  Description

Writes samples to quad channel 2 of an external device or stream.

  Syntax

outq2 asig

  Performance

Sends audio samples to an accumulating output buffer (created at the
beginning of performance) which serves to collect the output of all
active instruments before the sound is written to disk. There can be any
number of these output units in an instrument.

The type (mono, stereo, quad, hex, or oct) should agree with nchnls. But
as of version 3.50, Csound will attempt to change an incorrect opcode to
agree with the nchnls statement. Opcodes can be chosen to direct sound
to any particular channel: outs1 sends to stereo channel 1, outq3 to
quad channel 3, etc.


===========================================================================
outq3                                                                 *outq3*

  Description

Writes samples to quad channel 3 of an external device or stream.

  Syntax

outq3 asig

  Performance

Sends audio samples to an accumulating output buffer (created at the
beginning of performance) which serves to collect the output of all
active instruments before the sound is written to disk. There can be any
number of these output units in an instrument.

The type (mono, stereo, quad, hex, or oct) should agree with nchnls. But
as of version 3.50, Csound will attempt to change an incorrect opcode to
agree with the nchnls statement. Opcodes can be chosen to direct sound
to any particular channel: outs1 sends to stereo channel 1, outq3 to
quad channel 3, etc.


===========================================================================
outq4                                                                 *outq4*

  Description

Writes samples to quad channel 4 of an external device or stream.

  Syntax

outq4 asig

  Performance

Sends audio samples to an accumulating output buffer (created at the
beginning of performance) which serves to collect the output of all
active instruments before the sound is written to disk. There can be any
number of these output units in an instrument.

The type (mono, stereo, quad, hex, or oct) should agree with nchnls. But
as of version 3.50, Csound will attempt to change an incorrect opcode to
agree with the nchnls statement. Opcodes can be chosen to direct sound
to any particular channel: outs1 sends to stereo channel 1, outq3 to
quad channel 3, etc.


===========================================================================
outq                                                                   *outq*

  Description

Writes 4-channel audio data to an external device or stream.

  Syntax

outq asig1, asig2, asig3, asig4

  Performance

Sends 4-channel audio samples to an accumulating output buffer (created
at the beginning of performance) which serves to collect the output of
all active instruments before the sound is written to disk. There can be
any number of these output units in an instrument.

The type (mono, stereo, quad, hex, or oct) should agree with nchnls. But
as of version 3.50, Csound will attempt to change an incorrect opcode to
agree with the nchnls statement. Opcodes can be chosen to direct sound
to any particular channel: outs1 sends to stereo channel 1, outq3 to
quad channel 3, etc.


===========================================================================
outrg                                                                 *outrg*

  Description

outrg outputs audio to a range of adjacent audio channels on the audio
output device.

  Syntax

outrg kstart, aout1 [,aout2, aout3, ..., aoutN]

  Performance

kstart - the number of the first channel of the output device to be
accessed (channel numbers starts with 1, which is the first channel)

aout1, aout2, ... aoutN - the arguments containing the audio to be
output to the corresponding output channels.

outrg allows to output a range of adjacent channels to the output
device. kstart indicates the first channel to be accessed (channel 1 is
the first channel). The user must be sure that the number obtained by
summing kstart plus the number of accessed channels -1 is <= nchnls.


===========================================================================
outs1                                                                 *outs1*

  Description

Writes samples to stereo channel 1 of an external device or stream.

  Syntax

outs1 asig

  Performance

Sends audio samples to an accumulating output buffer (created at the
beginning of performance) which serves to collect the output of all
active instruments before the sound is written to disk. There can be any
number of these output units in an instrument.

The type (mono, stereo, quad, hex, or oct) should agree with nchnls. But
as of version 3.50, Csound will attempt to change an incorrect opcode to
agree with the nchnls statement. Opcodes can be chosen to direct sound
to any particular channel: outs1 sends to stereo channel 1, outq3 to
quad channel 3, etc.


===========================================================================
outs2                                                                 *outs2*

  Description

Writes samples to stereo channel 2 of an external device or stream.

  Syntax

outs2 asig

  Performance

Sends audio samples to an accumulating output buffer (created at the
beginning of performance) which serves to collect the output of all
active instruments before the sound is written to disk. There can be any
number of these output units in an instrument.

The type (mono, stereo, quad, hex, or oct) should agree with nchnls. But
as of version 3.50, Csound will attempt to change an incorrect opcode to
agree with the nchnls statement. Opcodes can be chosen to direct sound
to any particular channel: outs1 sends to stereo channel 1, outq3 to
quad channel 3, etc.


===========================================================================
outs                                                                   *outs*

  Description

Writes stereo audio data to an external device or stream.

  Syntax

outs asig1, asig2

  Performance

Sends stereo audio samples to an accumulating output buffer (created at
the beginning of performance) which serves to collect the output of all
active instruments before the sound is written to disk. There can be any
number of these output units in an instrument.

The type (mono, stereo, quad, hex, or oct) should agree with nchnls. But
as of version 3.50, Csound will attempt to change an incorrect opcode to
agree with the nchnls statement. Opcodes can be chosen to direct sound
to any particular channel: outs1 sends to stereo channel 1, outq3 to
quad channel 3, etc.


===========================================================================
outvalue                                                           *outvalue*

  Description

Sends an irate or k-rate signal or string to a user-defined channel.

  Syntax

outvalue "channel name", ivalue

outvalue "channel name", kvalue

outvalue "channel name", "string"

  Performance

"channel name" -- An integer or string (in double-quotes) representing
channel.

ivalue, kvalue -- The value that is sent to the channel.

string -- The string or string variable that is sent to the channel.


===========================================================================
outx                                                                   *outx*

  Description

Writes 16-channel audio data to an external device or stream.

  Syntax

outx asig1, asig2, asig3, asig4, asig5, asig6, asig7, asig8, \
      asig9, asig10, asig11, asig12, asig13, asig14, asig15, asig16

  Performance

outx outputs 16 channels of audio.


===========================================================================
outz                                                                   *outz*

  Description

Writes multi-channel audio data from a ZAK array to an external device
or stream.

  Syntax

outz ksig1

  Performance

outz outputs from a ZAK array for nchnls of audio.


===========================================================================
p5gconnect                                                       *p5gconnect*

  Description

Opens and at control-rate polls a P5 Glove controller.

  Syntax

p5gconnect

  Initialization

The opcode locates a P5 Glove attached to the computer by USB, and
starts a listener thread to poll the device.

  Performance

Every control cycle the glove is polled for its position, and finger and
button states. These values are read by the p5gdata opcode.


===========================================================================
p5gdata                                                             *p5gdata*

  Description

Reads data fields from a P5 Glove controller.

  Syntax

kres p5gdata kcontrol

  Initialization

This opcode must be used in conjuction with a running p5gconnect opcode.

  Performance

kcontrol -- the code for which control to read

On each access a particular data item of the P5 glove is read. The
currently implemented controls are given below, together with the macro
name defined in the file p5g_mac:

0 (P5G_BUTTONS): returns a bit pattern for all buttons that were pressed.

1 (P5G_BUTTON_A): returns 1 if the button has just been pressed, or 0
otherwise.

2 (P5G_BUTTON_B): as above.

4 (P5G_BUTTON_C): as above.

8 (P5G_JUSTPUSH): returns a bit pattern for all buttons that have just
been pressed.

9 (P5G_JUSTPU_A): returns 1 if the A button has just been pressed.

10 (P5G_JUSTPU_B): as above.

12 (P5G_JUSTPU_C): as above.

16 (P5G_RELEASED): returns a bit pattern for all buttons that have just
been released.

17 (P5G_RELSED_A): returns 1 if the A button has just been released.

18 (P5G_RELSED_B): as above.

20 (P5G_RELSED_C): as above.

32 (P5G_FINGER_INDEX): returns the clench value of the index finger.

33 (P5G_FINGER_MIDDLE): as above.

34 (P5G_FINGER_RING): as above.

35 (P5G_FINGER_PINKY): as above with little finger.

36 (P5G_FINGER_THUMB): as above.

37 (P5G_DELTA_X): The X position of the glove.

38 (P5G_DELTA_Y): The Y position of the glove.

39 (P5G_DELTA_Z): The Z position of the glove.

40 (P5G_DELTA_XR): The X axis change (angle).

41 (P5G_DELTA_YR): as above.

42 (P5G_DELTA_ZR): as above.

43 (P5G_ANGLES): The general angle


===========================================================================
p                                                                         *p*

  Description

Show the value in a given p-field.

  Syntax

p(x) 

This function works at i-rate and k-rate.

  Initialization

x -- the number of the p-field.

  Performance

The value returned by the p function is the value in a p-field.


===========================================================================
pan2                                                                   *pan2*

  Description

Distribute an audio signal across two channels with a choice of methods.

  Syntax

a1, a2 pan2 asig, xp [, imode]

  Initialization

imode (optional) -- mode of the stereo positioning algorithm. 0
signifies equal power (harmonic) panning, 1 means the square root
method, 2 means simple linear and 3 means an alternative equal-power pan
(based on an UDO). The default value is 0.

  Performance

pan2 takes an input signal asig and distributes it across two outputs
(essentially stereo speakers) according to the control xp which can be
k- or a-rate. A zero value for xp indicates hard left, and a 1 is hard
right.


===========================================================================
pan                                                                     *pan*

  Description

Distribute an audio signal amongst four channels with localization control.

  Syntax

a1, a2, a3, a4 pan asig, kx, ky, ifn [, imode] [, ioffset]

  Initialization

ifn -- function table number of a stored pattern describing the
amplitude growth in a speaker channel as sound moves towards it from an
adjacent speaker. Requires extended guard-point.

imode (optional) -- mode of the kx, ky position values. 0 signifies raw
index mode, 1 means the inputs are normalized (0 - 1). The default value
is 0.

ioffset (optional) -- offset indicator for kx, ky. 0 infers the origin
to be at channel 3 (left rear); 1 requests an axis shift to the
quadraphonic center. The default value is 0.

  Performance

pan takes an input signal asig and distributes it amongst four outputs
(essentially quad speakers) according to the controls kx and ky. For
normalized input (mode=1) and no offset, the four output locations are
in order: left-front at (0,1), right-front at (1,1), left-rear at the
origin (0,0), and right-rear at (1,0). In the notation (kx, ky), the
coordinates kx and ky, each ranging 0 - 1, thus control the 'rightness'
and 'forwardness' of a sound location.

Movement between speakers is by amplitude variation, controlled by the
stored function table ifn. As kx goes from 0 to 1, the strength of the
right-hand signals will grow from the left-most table value to the
right-most, while that of the left-hand signals will progress from the
right-most table value to the left-most. For a simple linear pan, the
table might contain the linear function 0 - 1. A more correct pan that
maintains constant power would be obtained by storing the first quadrant
of a sinusoid. Since pan will scale and truncate kx and ky in simple
table lookup, a medium-large table (say 8193) should be used.

kx, ky values are not restricted to 0 - 1. A circular motion passing
through all four speakers (inscribed) would have a diameter of root 2,
and might be defined by a circle of radius R = root 1/2 with center at
(.5,.5). kx, ky would then come from Rcos(angle), Rsin(angle), with an
implicit origin at (.5,.5) (i.e. ioffset = 1). Unscaled raw values
operate similarly. Sounds can thus be located anywhere in the polar or
Cartesian plane; points lying outside the speaker square are projected
correctly onto the square's perimeter as for a listener at the center.


===========================================================================
pareq                                                                 *pareq*

  Description

Implementation of Zoelzer's parametric equalizer filters, with some
modifications by the author.

The formula for the low shelf filter is:

omega = 2*pi*f/sr
K     = tan(omega/2)

b0    = 1 + sqrt(2*V)*K + V*K^2
b1    = 2*(V*K^2 - 1)
b2    = 1 - sqrt(2*V)*K + V*K^2

a0    = 1 + K/Q + K^2
a1    = 2*(K^2 - 1)
a2    = 1 - K/Q + K^2

The formula for the high shelf filter is:

omega = 2*pi*f/sr
K     = tan((pi-omega)/2)

b0    = 1 + sqrt(2*V)*K + V*K^2
b1    = -2*(V*K^2 - 1)
b1    = 1 - sqrt(2*V)*K + V*K^2

a0    = 1 + K/Q + K^2
a1    = -2*(K^2 - 1)
a2    = 1 - K/Q + K^2

The formula for the peaking filter is:

omega = 2*pi*f/sr
K     = tan(omega/2)

b0 =  1 + V*K/2 + K^2
b1 =  2*(K^2 - 1)
b2 =  1 - V*K/2 + K^2

a0 =  1 + K/Q + K^2
a1 =  2*(K^2 - 1)
a2 =  1 - K/Q + K^2

  Syntax

ares pareq asig, kc, kv, kq [, imode] [, iskip]

  Initialization

imode (optional, default: 0) -- operating mode

  * 0 = Peaking

  * 1 = Low Shelving

  * 2 = High Shelving

iskip (optional, default=0) -- if non zero skip the initialisation of
the filter. (New in Csound version 4.23f13 and 5.0)

  Performance

kc -- center frequency in peaking mode, corner frequency in shelving mode.

kv -- amount of boost or cut. A value less than 1 is a cut. A value
greater than 1 is a boost. A value of 1 is a flat response.

kq -- Q of the filter (sqrt(.5) is no resonance)

asig -- the incoming signal


===========================================================================
partials                                                           *partials*

  Description

The partials opcode takes two input PV streaming signals containg
AMP_FREQ and AMP_PHASE signals (as generated for instance by pvsifd or
in the first case, by pvsanal) and performs partial track analysis, as
described in Lazzarini et al, "Time-stretching using the Instantaneous
Frequency Distribution and Partial Tracking", Proc.of ICMC05, Barcelona.
It generates a TRACKS PV streaming signal, containing amplitude,
frequency, phase and track ID for each output track. This type of signal
will contain a variable number of output tracks, up to the total number
of analysis bins contained in the inputs (fftsize/2 + 1 bins). The
second input (AMP_PHASE) is optional, as it can take the same signal as
the first input. In this case, however, all phase information will be
NULL and resynthesis using phase information cannot be performed.

  Syntax

ftrks partials ffr, fphs, kthresh, kminpts, kmaxgap, imaxtracks

  Performance

ftrks -- output pv stream in TRACKS format

ffr -- input pv stream in AMP_FREQ format

fphs -- input pv stream in AMP_PHASE format

kthresh -- analysis threshold factor, defined between -1 and 1. If
non-negative, the analysis threshold is taken to be relative to the
maximum magnitude in each analysis frame (kthresh * max_magnitude). If
negative, the absolute threshold value is relative to 0dbfs (kthresh *
0dbfs). Tracks below this threshold will be discarded.

kminpoints -- minimum number of time points for a detected peak to make
a track (1 is the minimum). Since this opcode works with streaming
signals, larger numbers will increase the delay between input and
output, as we have to wait for the required minimum number of points.

kmaxgap -- maximum gap between time-points for track continuation (> 0).
Tracks that have no continuation after kmaxgap will be discarded.

imaxtracks -- maximum number of analysis tracks (number of bins >=
imaxtracks)


===========================================================================
partikkel                                                         *partikkel*

  Description

partikkel was conceived after reading Curtis Roads' book "Microsound",
and the goal was to create an opcode that was capable of all time-domain
varieties of granular synthesis described in this book. The idea being
that most of the techniques only differ in parameter values, and by
having a single opcode that can do all varieties of granular synthesis
makes it possible to interpolate between techniques. Granular synthesis
is sometimes dubbed particle synthesis, and it was thought apt to name
the opcode partikkel to distinguish it from other granular opcodes.

Some of the input parameters to partikkel is table numbers, pointing to
tables where values for the "per grain" parameter changes are stored.
partikkel can use single-cycle or complex (e.g. sampled sound) waveforms
as source waveforms for grains. Each grain consists of a mix of 4 source
waveforms. Individual tuning of the base frequency can be done for each
of the 4 source waveforms. Frequency modulation inside each grain is
enabled via an auxillary audio input (awavfm). Trainlet synthesis is
available, and trainlets can be mixed with wavetable based grains. Up to
8 separate audio outputs can be used.

  Syntax

a1 [, a2, a3, a4, a5, a6, a7, a8] partikkel agrainfreq, \
              kdistribution, idisttab, async, kenv2amt, ienv2tab, ienv_attack, \
              ienv_decay, ksustain_amount, ka_d_ratio, kduration, kamp, igainmasks, \
              kwavfreq, ksweepshape, iwavfreqstarttab, iwavfreqendtab, awavfm, \
              ifmamptab, kfmenv, icosine, ktraincps, knumpartials, kchroma, \
              ichannelmasks, krandommask, kwaveform1, kwaveform2, kwaveform3, \
              kwaveform4, iwaveamptab, asamplepos1, asamplepos2, asamplepos3, \
              asamplepos4, kwavekey1, kwavekey2, kwavekey3, kwavekey4, imax_grains \
              [, iopcode_id]

  Initialization

idisttab -- function table number, distribution for random grain
displacements over time. The table values are interpreted as
"displacement amount" scaled by 1/grainrate. This means that a value of
0.5 in the table will displace a grain by half the grainrate period. The
table values are read randomly, and scaled by kdistribution. For
realistic stochastic results, it is advisable not to use a too small
table size, as this limits the amount of possible displacement values.
This can also be utilized for other purposes, e.g. using quantized
displacement values to work with controlled time displacement from the
periodic grain rate. If kdistribution is negative, the table values will
be read sequentially. A default table might be selected by using -1 as
the ftable number, for idisttab the default uses a zero distribution (no
displacement).

ienv_attack -- function table number, attack shape of grain. Needs
extended guard point. A default table might be selected by using -1 as
the ftable number, for ienv_attack the default uses a square window (no
enveloping).

ienv_decay -- function table number, decay shape of grain. Needs
extended guard point. A default table might be selected by using -1 as
the ftable number, for ienv_decay the default uses a square window (no
enveloping).

ienv2tab -- function table number, additional envelope applied to grain,
done after attack and decay envelopes. Can be used e.g. for fof formant
synthesis. Needs extended guard point. A default table might be selected
by using -1 as the ftable number, for ienv2tab the default uses a square
window (no enveloping).

icosine -- function table number, must contain a cosine, used for
trainlets. Table size should be at least 2048 for good quality trainlets.

igainmasks -- function table number, gain per grain. The sequence of
values in the table is as follows: index 0 is used as a loop start point
in reading the values, index 1 is used as a loop end point. Remaining
indices contain gain values (normally in range 0 - 1, but other values
are allowed, negative values will invert phase of waveform inside grain)
for a sequence of grains, these are read at grain rate enabling exact
patterns of "gain per grain". The loop start and end points are zero
based with an origin at index 2, e.g. a loop start value of 0 and loop
end value of 3 will read indices 2,3,4,5 in a loop at grain rate. A
default table might be selected by using -1 as the ftable number, for
igainmasks the default disables gain masking (all grains are given a
gain masking value of 1).

ichannelmasks -- function table number, see igainmasks for a description
of how the values in the table are read. Range is 0 to N, where N is the
number of output channels minus 1. A value of zero will send the grain
to audio output 1 from the opcode. Fractional values are allowed, e.g. a
value of 3.5 will mix the grain equally to outputs 4 and 5. The user is
responsible for keeping the values in range, no range checking is done.
The opcode will crash with out of range values. A default table might be
selected by using -1 as the ftable number, for ichannelmasks the default
disables channel masking (all grains are given a channel masking value
of 0 and are sent to partikkel audio out 1).

iwavfreqstarttab -- function table number, see igainmasks for a
description of how the values in the table are read. Start frequency
multiplicator for each grain. Pitch will glide from start frequency to
end frequency following a line or curve as set by ksweepshape. A default
table might be selected by using -1 as the ftable number, for
iwavfreqstarttab the default uses a multiplicator of 1, disabling any
start frequency modification.

iwavfreqendtab -- function table number, see iwavfreqstarttab. End
frequency multiplicator for each grain. A default table might be
selected by using -1 as the ftable number, for iwavfreqendtab the
default uses a multiplicator of 1, disabling any end frequency
modification.

ifmamptab -- function table number, see igainmasks for a description of
how the values in the table are read. Frequency modulation index per
grain. The signal awavfm will be multiplied by values read from this
table. A default table might be selected by using -1 as the ftable
number, for ifmamptab the default uses 1 as the index multiplicator,
enabling fm for all grains.

iwaveamptab -- function table number, the indices are read in a similar
way to what is used for igainmasks. Index 0 is used as a loop start
point, and index 1 is used as a loop end point. The rest of the indices
are read in groups of 5, where each value represent a gain value for
each of the 4 source waveforms, and the 5th value represent trainlet
amplitude. A default table might be selected by using -1 as the ftable
number, for iwaveamptab the default uses an equal mix of all 4 source
waveforms (each with an amplitude of 0.5) and setting trainlet amp to zero.

Computation of trainlets can be CPU intensive, and setting ktrainamp to
zero will skip most of the trainlet computations. Trainlets will be
normalized to peak (ktrainamp), compensating for amplitude variations
caused by variations in kpartials and kchroma.

imax_grains -- maximum number of grains per k-period. Estimating a large
value should not affect performance, exceeding this value will lead to
"oldest grains" being deleted.

iopcode_id -- the opcode id, linking an instance of partikkel to an
instance of partikkelsync, the linked partikkelsync will output trigger
pulses synchronized to partikkel's grain maker scheduler. The default
value is zero, which means no connection to any partikkelsync instances.

  Performance

xgrainfreq -- number of grains per second. A value of zero is allowed,
and this will defer all grain scheduling to the sync input.

async -- sync input. Input values are added to the phase value of the
internal grain maker clock, enabling tempo synchronization with an
external clock source. As this is an a-rate signal, inputs are usually
pulses of length 1/sr. Using such pulses, the internal phase value can
be "nudged" up or down, enabling soft or hard synchronization. Negative
input values decrements the internal phase, while positive values in the
range 0 to 1 increments the internal phase. An input value of 1 will
always make partikkel generate a grain. If the value remains at 1, the
internal grain scheduler clock will pause but any currently playing
grains will still play to end.

kdistribution -- periodic or stochastic distribution of grains, 0 =
periodic. Stochastic grain displacement is in the range of
kdistribution/grainrate seconds. The stochastic distribution profile
(random distribution) can be set in the idisttab table. If kdistribution
is negative, the result is deterministic time displacement as described
by idisttab (sequential read of displacement values). Maximum grain
displacement in all cases is limited to 10 seconds, and a grain will
keep the values (duration, pitch etc) it was given when it was first
generated (before time displacement). Since grain displacement is
relative to the grain rate, displacement amount is undefined at 0Hz
grain rate and kdistribution is completely disabled in this case.

kenv2amt -- amount of enveloping for the secondary envelope for each
grain. Range 0 to 1, where 0 is no secondary enveloping (square window),
a value of 0.5 will use an interpolation between a square window and the
shape set by ienv2tab.

ksustain_amount -- sustain time as fraction of grain duration. I.e.
balance between enveloped time(attack+decay) and sustain level time. The
sustain level is taken from the last value of the ienv_attack ftable.

ka_d_ratio -- balance between attack time and decay time. For example,
with ksustain_amount set to 0.5 and ka_d_ratio set to 0.5, the attack
envelope of each grain will take 25% of the grain duration, full
amplitude (sustain) will be held for 50% of the grain duration, and the
decay envelope will take the remaining 25% of the grain duration.

kduration -- grain duration in milliseconds.

kamp -- amplitude scaling of the opcode's output. Multiplied by per
grain amplitude read from igainmasks. Source waveform playback inside
grains can consume a significant amount of CPU cycles, especially if
grain duration is long so that we have a lot of overlapping grains.
Setting kamp to zero will skip waveform playback inside grains (and not
generate any sound, obviously). This can be used as a "soft" bypass
method if we want to keep the opcode active but silent for some periods
of time.

kwavfreq -- transposition scaling. Multiplied with start and end
transposition values read from iwavfreqstarttab and iwavfreqendtab.

ksweepshape -- transposition sweep shape, controls the curvature of the
transposition sweep. Range 0 to 1. Low values will hold the
transposition at the start value longer and then drop to the end value
quickly, high values will drop to the end value quickly. A value of 0.5
will give a linear sweep. A value of exactly 0 will bypass sweep and
only use the start frequency, while a value of exactly 1 will bypass
sweep and only use the end frequency. The sweep generator might be
slightly inaccurate in hitting the end frequency when using a steep
curve and very long grains.

awavfm -- audio input for frequency modulation inside grain.

kfmenv -- function table number, envelope for FM modulator signal
enabling the modulation index to change over the duration of a grain.

ktraincps -- trainlet fundamental frequency.

knumpartials -- number of partials in trainlets.

kchroma -- chroma of trainlets. A value of 1 give equal amplitude to
each partial, higher values will reduce the amplitude of lower partials
while strengthening the amplitude of the higher partials.

krandommask -- random masking (muting) of individual grains. Range 0 to
1, where a value of 0 will give no masking (all grains are played), and
a value of 1 will mute all grains.

kwaveform1 -- table number for source waveform 1.

kwaveform2 -- table number for source waveform 2.

kwaveform3 -- table number for source waveform 3.

kwaveform4 -- table number for source waveform 4.

asamplepos1 -- start position for reading source waveform 1 (in range
0..1).

asamplepos2 -- start position for reading source waveform 2.

asamplepos3 -- start position for reading source waveform 3.

asamplepos4 -- start position for reading source waveform 4.

kwavekey1 -- original key of source waveform 1. Can be used to transpose
each source waveform independently.

kwavekey2 -- as kwavekey1, but for source waveform 2.

kwavekey3 -- as kwavekey1, but for source waveform 3.

kwavekey4 -- as kwavekey1, but for source waveform 4.


===========================================================================
partikkelsync                                                 *partikkelsync*

  Description

partikkelsync is an opcode for outputting partikkel's grain scheduler
clock pulse and phase. partikkelsync's output can be used to synchronize
other instances of the partikkel opcode to the same clock.

  Syntax

async [,aphase] partikkelsync iopcode_id

  Initialization

iopcode_id -- the opcode id, linking an instance of partikkel to an
instance of partikkelsync.

  Performance

async -- trigger pulse signal. Outputs trigger pulses synchronized to a
partikkel opcode's grain scheduler clock. One trigger pulse is generated
for each grain started in the partikkel opcode with the same opcode_id.
The normal usage would be to send this signal to another partikkel
opcode's async input to synchronize several instances of partikkel.

aphase -- clock phase. Outputs a linear ramping phase signal. Can be
used e.g. for softsynchronization, or just as a phase generator ala phasor.


===========================================================================
passign                                                             *passign*

  Description

Assigns a range of p-fields to ivariables.

  Syntax

 ivar1, ... passign [istart]

  Initialisation

The optional argument istart gives the index of the first p-field to
assign. The default value is 1, corresponding to the instrument number.

One of the variables can be a string variable, in which case it is
assigned the only string parameter, if there is one, or an error otherwise.

  Performance

passign transfers the instrument p-fields to instrument variables,
starting with the one identified by the istart argument. There should
not be more variables than p-fields, but there may be fewer.


===========================================================================
paulstretch                                                     *paulstretch*

  Description

The paulstretch opcode is a lightweight implementation of the
PaulStretch time-stretching algorithm by Nasca Octavian Paul. It is
ideal for timestretching a signal by very large amounts.

The Paulstretch algorithm works very similarly to other STFT-based
timestretching methods, using overlap-add with a hanning window. Unique
to paulstretch are the use of scrambled phase and very large window
sizes (specified in seconds).

  Syntax

asig paulstretch istretch, iwindowsize, ift

  Initialization

istretch -- Stretch factor.

iwindowsize -- Window size, in seconds.

ift -- source signal function table. Deferred-allocation tables (see
GEN01) are accepted, but the opcode expects a mono source.


===========================================================================
pcauchy                                                             *pcauchy*

  Description

Cauchy distribution random number generator (positive values only). This
is an x-class noise generator.

  Syntax

ares pcauchy kalpha

ires pcauchy kalpha

kres pcauchy kalpha

  Performance

pcauchy kalpha -- controls the spread from zero (big kalpha = big
spread). Outputs positive numbers only.

For more detailed explanation of these distributions, see:

 1. C. Dodge - T.A. Jerse 1985. Computer music. Schirmer books. pp.265 - 286

 2. D. Lorrain. A panoply of stochastic cannons. In C. Roads, ed. 1989.
    Music machine . Cambridge, Massachusetts: MIT press, pp. 351 - 379.


===========================================================================
pchbend                                                             *pchbend*

  Description

Get the current pitch-bend value for this channel.

  Syntax

ibend pchbend [imin] [, imax]

kbend pchbend [imin] [, imax]

  Initialization

imin, imax (optional) -- set minimum and maximum limits on values obtained

  Performance

Get the current pitch-bend value for this channel. Note that this access
to pitch-bend data is independent of the MIDI pitch, enabling the value
here to be used for any arbitrary purpose.


===========================================================================
pchmidi                                                             *pchmidi*

  Description

Get the note number of the current MIDI event, expressed in pitch-class
units.

  Syntax

ipch pchmidi

  Performance

Get the note number of the current MIDI event, expressed in pitch-class
units for local processing.

  pchmidi vs. pchmidinn

The pchmidi opcode only produces meaningful results in a Midi-activated
note (either real-time or from a Midi score with the -F flag). With
pchmidi, the Midi note number value is taken from the Midi event that is
internally associated with the instrument instance. On the other hand,
the pchmidinn opcode may be used in any Csound instrument instance
whether it is activated from a Midi event, score event, line event, or
from another instrument. The input value for pchmidinn might for example
come from a p-field in a textual score or it may have been retrieved
from the real-time Midi event that activated the current note using the
notnum opcode.


===========================================================================
pchmidib                                                           *pchmidib*

  Description

Get the note number of the current MIDI event and modify it by the
current pitch-bend value, express it in pitch-class units.

  Syntax

ipch pchmidib [irange]

kpch pchmidib [irange]

  Initialization

irange (optional) -- the pitch bend range in semitones

  Performance

Get the note number of the current MIDI event, modify it by the current
pitch-bend value, and express the result in pitch-class units. Available
as an i-time value or as a continuous k-rate value.


===========================================================================
pchmidinn                                                         *pchmidinn*

  Description

Converts a Midi note number value to octave point pitch-class units.

  Syntax

pchmidinn (MidiNoteNumber)  (init- or control-rate args only)

where the argument within the parentheses may be a further expression.

  Performance

pchmidinn is a function that takes an i-rate or k-rate value
representing a Midi note number and returns the equivalent pitch value
in Csound's octave point pitch-class format. This conversion assumes
that Middle C (8.00 in pch) is Midi note number 60. Midi note number
values are typically integers in the range from 0 to 127 but fractional
values or values outside of this range will be interpreted consistently.

  pchmidinn vs. pchmidi

The pchmidinn opcode may be used in any Csound instrument instance
whether it is activated from a Midi event, score event, line event, or
from another instrument. The input value for pchmidinn might for example
come from a p-field in a textual score or it may have been retrieved
from the real-time Midi event that activated the current note using the
notnum opcode. You must specify an i-rate or k-rate expression for the
Midi note number that is to be converted. On the other hand, the pchmidi
opcode only produces meaningful results in a Midi-activated note (either
real-time or from a Midi score with the -F flag). With pchmidi, the Midi
note number value is taken from the Midi event associated with the
instrument instance, and no location or expression for this value may be
specified.

pchmidinn and its related opcodes are really value converters with a
special function of manipulating pitch data.

Data concerning pitch and frequency can exist in any of the following
forms:

Table 19. Pitch and Frequency Values

Name    Abbreviation
octave point pitch-class (8ve.pc)       pch
octave point decimal    oct
cycles per second       cps
Midi note number (0-127)        midinn

The first two forms consist of a whole number, representing octave
registration, followed by a specially interpreted fractional part. For
pch, the fraction is read as two decimal digits representing the 12
equal-tempered pitch classes from .00 for C to .11 for B. For oct, the
fraction is interpreted as a true decimal fractional part of an octave.
The two fractional forms are thus related by the factor 100/12. In both
forms, the fraction is preceded by a whole number octave index such that
8.00 represents Middle C, 9.00 the C above, etc. Midi note number values
range between 0 and 127 (inclusively) with 60 representing Middle C, and
are usually whole numbers. Thus A440 can be represented alternatively by
440 (cps), 69 (midinn), 8.09 (pch), or 8.75 (oct). Microtonal divisions
of the pch semitone can be encoded by using more than two decimal places.

The mnemonics of the pitch conversion units are derived from morphemes
of the forms involved, the second morpheme describing the source and the
first morpheme the object (result). Thus cpspch(8.09) will convert the
pitch argument 8.09 to its cps (or Hertz) equivalent, giving the value
of 440. Since the argument is constant over the duration of the note,
this conversion will take place at i-time, before any samples for the
current note are produced.

By contrast, the conversion cpsoct(8.75 + k1) which gives the value of
A440 transposed by the octave interval k1. The calculation will be
repeated every k-period since that is the rate at which k1 varies.

  Note

The conversion from pch, oct, or midinn into cps is not a linear
operation but involves an exponential process that could be
time-consuming when executed repeatedly. Csound now uses a built-in
table lookup to do this efficiently, even at audio rates. Because the
table index is truncated without interpolation, pitch resolution when
using one of these opcodes is limited to 8192 discrete and equal
divisions of the octave, and some pitches of the standard 12-tone
equally-tempered scale are very slightly mistuned (by at most 0.15 cents).


===========================================================================
pchoct                                                               *pchoct*

  Description

Converts an octave-point-decimal value to pitch-class.

  Syntax

pchoct (oct)  (init- or control-rate args only)

where the argument within the parentheses may be a further expression.

  Performance

pchoct and its related opcodes are really value converters with a
special function of manipulating pitch data.

Data concerning pitch and frequency can exist in any of the following
forms:

Table 20. Pitch and Frequency Values

Name    Abbreviation
octave point pitch-class (8ve.pc)       pch
octave point decimal    oct
cycles per second       cps
Midi note number (0-127)        midinn

The first two forms consist of a whole number, representing octave
registration, followed by a specially interpreted fractional part. For
pch, the fraction is read as two decimal digits representing the 12
equal-tempered pitch classes from .00 for C to .11 for B. For oct, the
fraction is interpreted as a true decimal fractional part of an octave.
The two fractional forms are thus related by the factor 100/12. In both
forms, the fraction is preceded by a whole number octave index such that
8.00 represents Middle C, 9.00 the C above, etc. Midi note number values
range between 0 and 127 (inclusively) with 60 representing Middle C, and
are usually whole numbers. Thus A440 can be represented alternatively by
440 (cps), 69 (midinn), 8.09 (pch), or 8.75 (oct). Microtonal divisions
of the pch semitone can be encoded by using more than two decimal places.

The mnemonics of the pitch conversion units are derived from morphemes
of the forms involved, the second morpheme describing the source and the
first morpheme the object (result). Thus cpspch(8.09) will convert the
pitch argument 8.09 to its cps (or Hertz) equivalent, giving the value
of 440. Since the argument is constant over the duration of the note,
this conversion will take place at i-time, before any samples for the
current note are produced.

By contrast, the conversion cpsoct(8.75 + k1) which gives the value of
A440 transposed by the octave interval k1. The calculation will be
repeated every k-period since that is the rate at which k1 varies.

  Note

The conversion from pch, oct, or midinn into cps is not a linear
operation but involves an exponential process that could be
time-consuming when executed repeatedly. Csound now uses a built-in
table lookup to do this efficiently, even at audio rates. Because the
table index is truncated without interpolation, pitch resolution when
using one of these opcodes is limited to 8192 discrete and equal
divisions of the octave, and some pitches of the standard 12-tone
equally-tempered scale are very slightly mistuned (by at most 0.15 cents).


===========================================================================
pconvolve                                                         *pconvolve*

  Description

Convolution based on a uniformly partitioned overlap-save algorithm.
Compared to the convolve opcode, pconvolve has these benefits:

  * small delay

  * possible to run in real-time for shorter impulse files

  * no pre-process analysis pass

  * can often render faster than convolve

  Syntax

ar1 [, ar2] [, ar3] [, ar4] pconvolve ain, ifilcod [, ipartitionsize, ichannel]

  Initialization

ifilcod -- integer or character-string denoting an impulse response
soundfile. Multichannel files are supported, the file must have the same
sample-rate as the orc. [Note: cvanal files cannot be used!] Keep in
mind that longer files require more calculation time [and probably
larger partition sizes and more latency]. At current processor speeds,
files longer than a few seconds may not render in real-time.

ipartitionsize (optional, defaults to the output buffersize [-b]) -- the
size in samples of each partition of the impulse file. This is the
parameter that needs tweaking for best performance depending on the
impulse file size. Generally, a small size means smaller latency but
more computation time. If you specify a value that is not a power-of-2
the opcode will find the next power-of-2 greater and use that as the
actual partition size.

ichannel (optional) -- which channel to use from the impulse response
data file.

  Performance

ain -- input audio signal.

The overall latency of the opcode can be calculated as such [assuming
ipartitionsize is a power of 2]

===========================================================================
ilatency = (ksmps < ipartitionsize ? ipartitionsize + ksmps : ipartitionsize)/sr     *ilatency*


===========================================================================
pcount                                                               *pcount*

  Description

pcount returns the number of pfields belonging to a note event.

  Syntax

icount pcount

  Initialization

icount - stores the number of pfields for the current note event.

  Note

Note that the reported number of pfields is not necessarily what's
explicitly written in the score, but the pfields available to the
instrument through mechanisms like pfield carry.


===========================================================================
pdclip                                                               *pdclip*

  Description

The pdclip opcode allows a percentage of the input range of a signal to
be clipped to fullscale. It is similar to simply multiplying the signal
and limiting the range of the result, but pdclip allows you to think
about how much of the signal range is being distorted instead of the
scalar factor and has a offset parameter for assymetric clipping of the
signal range. pdclip is also useful for remapping phasors for phase
distortion synthesis.

  Syntax

aout pdclip ain, kWidth, kCenter [, ibipolar [, ifullscale]]

  Initialization

ibipolar -- an optional parameter specifying either unipolar (0) or
bipolar (1) mode. Defaults to unipolar mode.

ifullscale -- an optional parameter specifying the range of input and
output values. The maximum will be ifullscale. The minimum depends on
the mode of operation: zero for unipolar or -ifullscale for bipolar.
Defaults to 1.0 -- you should set this parameter to the maximum expected
input value.

  Performance

ain -- the input signal to be clipped.

aout -- the output signal.

kWidth -- the percentage of the signal range that is clipped (must be
between 0 and 1).

kCenter -- an offset for shifting the unclipped window of the signal
higher or lower in the range (essentially a DC offset). Values should be
in the range [-1, 1] with a value of zero representing no shift
(regardless of whether bipolar or unipolar mode is used).

The pdclip opcode performs linear clipping on the input signal ain.
kWidth specifies the percentage of the signal range that is clipped. The
rest of the input range is mapped linearly from zero to ifullscale in
unipolar mode and from -ifullscale to ifullscale in bipolar mode. When
kCenter is zero, equal amounts of the top and bottom of the signal range
are clipped. A negative value shifts the unclipped range more towards
the bottom of the input range and a positive value shifts it more
towards the top. ibipolar should be 1 for bipolar operation and 0 for
unipolar mode. The default is unipolar mode (ibipolar = 0). ifullscale
sets the maximum amplitude of the input and output signals (defaults to
1.0).

This amounts to waveshaping the input with the following transfer
function (normalized to ifullscale=1.0 in bipolar mode):

        1|   _______      x-axis is input range, y-axis is output
         |  /       
         | /              width of clipped region is 2*kWidth
-1       |/        1      width of unclipped region is 2*(1 - kWidth)
--------------------      kCenter shifts the unclipped region
        /|                 left or right (up to kWidth)
       / |
      /  |
------   |-1

Bipolar mode can be used for direct, linear distortion of an audio
signal. Alternatively, unipolar mode is useful for modifying the output
of a phasor before it is used to index a function table, effectively
making this a phase distortion technique.


===========================================================================
pdhalf                                                               *pdhalf*

  Description

The pdhalf opcode is designed to emulate the "classic" phase distortion
synthesis method of the Casio CZ-series of synthesizers from the
mid-1980's. This technique reads the first and second halves of a
function table at different rates in order to warp the waveform. For
example, pdhalf can smoothly transform a sine wave into something
approximating the shape of a saw wave.

  Syntax

aout pdhalf ain, kShapeAmount [, ibipolar [, ifullscale]]

  Initialization

ibipolar -- an optional parameter specifying either unipolar (0) or
bipolar (1) mode. Defaults to unipolar mode.

ifullscale -- an optional parameter specifying the range of input and
output values. The maximum will be ifullscale. The minimum depends on
the mode of operation: zero for unipolar or -ifullscale for bipolar.
Defaults to 1.0 -- you should set this parameter to the maximum expected
input value.

  Performance

ain -- the input signal to be distorted.

aout -- the output signal.

kShapeAmount -- the amount of distortion applied to the input. Must be
between negative one and one (-1 to 1). An amount of zero means no
distortion.

Transfer function created by pdhalf and a negative kShapeAmount.

Transfer function created by pdhalf and a negative kShapeAmount.

The pdhalf opcode calculates a transfer function that is composed of two
linear segments (see the graph). These segments meet at a "pivot point"
which always lies on the same horizontal axis. (In unipolar mode, the
axis is y = 0.5, and for bipolar mode it is the x axis). The
kShapeAmount parameter specifies where on the horizontal axis this point
falls. When kShapeAmount is zero, the pivot point is in the middle of
the input range, forming a straight line for the transfer function and
thus causing no change in the input signal. As kShapeAmount changes from
zero (0) to negative one (-1), the pivot point moves towards the left
side of the graph, producing a phase distortion pattern like the Casio
CZ's "sawtooth waveform". As it changes from zero (0) to positive one
(1), the pivot point moves toward the right, producing an inverted pattern.

If the input to pdhalf is a phasor and the output is used to index a
table, values for kShapeAmount that are less than zero will cause the
first half of the table to be read more quickly than the second half.
The reverse is true for values of kShapeAmount greater than zero. The
rates at which the halves are read are calculated so that the frequency
of the phasor is unchanged. Thus, this method of phase distortion can
only produce higher partials in a harmonic series. It cannot produce
inharmonic sidebands in the way that frequency modulation does.

pdhalf can work in either unipolar or bipolar modes. Unipolar mode is
appropriate for signals like phasors that range between zero and some
maximum value (selectable with ifullscale). Bipolar mode is appropriate
for signals that range above and below zero by roughly equal amounts
such as most audio signals. Applying pdhalf directly to an audio signal
in this way results in a crude but adjustable sort of
waveshaping/distortion.

A typical example of the use of pdhalf is

    aphase    phasor    ifreq
    apd       pdhalf    aphase, kamount
    aout      tablei    apd, 1, 1


===========================================================================
pdhalfy                                                             *pdhalfy*

  Description

The pdhalfy opcode is a variation on the phase distortion synthesis
method of the pdhalf opcode. It is useful for distorting a phasor in
order to read two unequal portions of a table in the same number of
samples.

  Syntax

aout pdhalfy ain, kShapeAmount [, ibipolar [, ifullscale]]

  Initialization

ibipolar -- an optional parameter specifying either unipolar (0) or
bipolar (1) mode. Defaults to unipolar mode.

ifullscale -- an optional parameter specifying the range of input and
output values. The maximum will be ifullscale. The minimum depends on
the mode of operation: zero for unipolar or -ifullscale for bipolar.
Defaults to 1.0 -- you should set this parameter to the maximum expected
input value.

  Performance

ain -- the input signal to be distorted.

aout -- the output signal.

kShapeAmount -- the amount of distortion applied to the input. Must be
between negative one and one (-1 to 1). An amount of zero means no
distortion.

Transfer function created by pdhalfy and a negative kShapeAmount.

Transfer function created by pdhalfy and a negative kShapeAmount.

The pdhalfy opcode calculates a transfer function that is composed of
two linear segments (see the graph). These segments meet at a "pivot
point" which always lies on the same vertical axis. (In unipolar mode,
the axis is x = 0.5, and for bipolar mode it is the y axis). So, pdhalfy
is a variation of the pdhalf opcode that places the pivot point of the
phase distortion pattern on a vertical axis instead of a horizontal axis.

The kShapeAmount parameter specifies where on the vertical axis this
point falls. When kShapeAmount is zero, the pivot point is in the middle
of the output range, forming a straight line for the transfer function
and thus causing no change in the input signal. As kShapeAmount changes
from zero (0) to negative one (-1), the pivot point downward towards the
bottom of the graph. As it changes from zero (0) to positive one (1),
the pivot point moves upward, producing an inverted pattern.

If the input to pdhalfy is a phasor and the output is used to index a
table, the use of pdhalfy will divide the table into two segments of
different sizes with each segment being mapped to half of the oscillator
period. Values for kShapeAmount that are less than zero will cause less
than half of the table to be read in the first half of the period of
oscillation. The rest of the table will be read in the second half of
the period. The reverse is true for values of kShapeAmount greater than
zero. Note that the frequency of the phasor is always unchanged. Thus,
this method of phase distortion can only produce higher partials in a
harmonic series. It cannot produce inharmonic sidebands in the way that
frequency modulation does. pdhalfy tends to have a milder quality to its
distortion than pdhalf.

pdhalfy can work in either unipolar or bipolar modes. Unipolar mode is
appropriate for signals like phasors that range between zero and some
maximum value (selectable with ifullscale). Bipolar mode is appropriate
for signals that range above and below zero by roughly equal amounts
such as most audio signals. Applying pdhalfy directly to an audio signal
in this way results in a crude but adjustable sort of
waveshaping/distortion.

A typical example of the use of pdhalfy is

    aphase    phasor     ifreq
    apd       pdhalfy    aphase, kamount
    aout      tablei     apd, 1, 1


===========================================================================
peak                                                                   *peak*

  Description

These opcodes maintain the output k-rate variable as the peak absolute
level so far received.

  Syntax

kres peak asig

kres peak ksig

  Performance

kres -- Output equal to the highest absolute value received so far. This
is effectively an input to the opcode as well, since it reads kres in
order to decide whether to write something higher into it.

ksig -- k-rate input signal.

asig -- a-rate input signal.


===========================================================================
pgmassign                                                         *pgmassign*

  Description

Assigns an instrument number to a specified (or all) MIDI program(s).

By default, the instrument is the same as the program number. If the
selected instrument is zero or negative or does not exist, the program
change is ignored. This opcode is normally used in the orchestra header.
Although, like massign, it also works in instruments.

  Syntax

pgmassign ipgm, inst[, ichn]

pgmassign ipgm, "insname"[, ichn]

  Initialization

ipgm -- MIDI program number (1 to 128). A value of zero selects all
programs.

inst -- instrument number. If set to zero, or negative, MIDI program
changes to ipgm are ignored. Currently, assignment to an instrument that
does not exist has the same effect. This may be changed in a later
release to print an error message.

“insname” -- A string (in double-quotes) representing a named instrument.

“ichn” (optional, defaults to zero) -- channel number. If zero, program
changes are assigned on all channels.

You can disable the turning on of any instruments by using the following
in the header:

        massign 0, 0
        pgmassign 0, 0


===========================================================================
phaser1                                                             *phaser1*

  Description

An implementation of iord number of first-order allpass filters in series.

  Syntax

ares phaser1 asig, kfreq, kord, kfeedback [, iskip]

  Initialization

iskip (optional, default=0) -- used to control initial disposition of
internal data space. Since filtering incorporates a feedback loop of
previous output, the initial status of the storage space used is
significant. A zero value will clear the space; a non-zero value will
allow previous information to remain. The default value is 0.

  Performance

kfreq -- frequency (in Hz) of the filter(s). This is the frequency at
which each filter in the series shifts its input by 90 degrees.

kord -- the number of allpass stages in series. These are first-order
filters and can range from 1 to 4999.

  Note

Although kord is listed as k-rate, it is in fact accessed only at
init-time. So if you are using a k-rate argument, it must be assigned
with init.

kfeedback -- amount of the output which is fed back into the input of
the allpass chain. With larger amounts of feedback, more prominent
notches appear in the spectrum of the output. kfeedback must be between
-1 and +1. for stability.

phaser1 implements iord number of first-order allpass sections, serially
connected, all sharing the same coefficient. Each allpass section can be
represented by the following difference equation:

y(n) = C * x(n) + x(n-1) - C * y(n-1)

where x(n) is the input, x(n-1) is the previous input, y(n) is the
output, y(n-1) is the previous output, and C is a coefficient which is
calculated from the value of kfreq, using the bilinear z-transform.

By slowly varying kfreq, and mixing the output of the allpass chain with
the input, the classic "phase shifter" effect is created, with notches
moving up and down in frequency. This works best with iord between 4 and
16. When the input to the allpass chain is mixed with the output, 1
notch is generated for every 2 allpass stages, so that with iord = 6,
there will be 3 notches in the output. With higher values for iord,
modulating kfreq will result in a form of nonlinear pitch modulation.


===========================================================================
phaser2                                                             *phaser2*

  Description

An implementation of iord number of second-order allpass filters in series.

  Syntax

ares phaser2 asig, kfreq, kq, kord, kmode, ksep, kfeedback

  Performance

kfreq -- frequency (in Hz) of the filter(s). This is the center
frequency of the notch of the first allpass filter in the series. This
frequency is used as the base frequency from which the frequencies of
the other notches are derived.

kq -- Q of each notch. Higher Q values result in narrow notches. A Q
between 0.5 and 1 results in the strongest "phasing" effect, but higher
Q values can be used for special effects.

kord -- the number of allpass stages in series. These are second-order
filters, and iord can range from 1 to 2499. With higher orders, the
computation time increases.

kfeedback -- amount of the output which is fed back into the input of
the allpass chain. With larger amounts of feedback, more prominent
notches appear in the spectrum of the output. kfeedback must be between
-1 and +1. for stability.

kmode -- used in calculation of notch frequencies.

  Note

Although kord and kmode are listed as k-rate, they are in fact accessed
only at init-time. So if you are using k-rate arguments, they must be
assigned with init.

ksep -- scaling factor used, in conjunction with imode, to determine the
frequencies of the additional notches in the output spectrum.

phaser2 implements iord number of second-order allpass sections,
connected in series. The use of second-order allpass sections allows for
the precise placement of the frequency, width, and depth of notches in
the frequency spectrum. iord is used to directly determine the number of
notches in the spectrum; e.g. for iord = 6, there will be 6 notches in
the output spectrum.

There are two possible modes for determining the notch frequencies. When
imode = 1, the notch frequencies are determined by the following function:

frequency of notch N = kbf + (ksep * kbf * N-1)

For example, with imode = 1 and ksep = 1, the notches will be in
harmonic relationship with the notch frequency determined by kfreq (i.e.
if there are 8 notches, with the first at 100 Hz, the next notches will
be at 200, 300, 400, 500, 600, 700, and 800 Hz). This is useful for
generating a "comb filtering" effect, with the number of notches
determined by iord. Different values of ksep allow for inharmonic notch
frequencies and other special effects. ksep can be swept to create an
expansion or contraction of the notch frequencies. A useful visual
analogy for the effect of sweeping ksep would be the bellows of an
accordion as it is being played - the notches will be seperated, then
compressed together, as ksep changes.

When imode = 2, the subsequent notches are powers of the input parameter
ksep times the initial notch frequency specified by kfreq. This can be
used to set the notch frequencies to octaves and other musical
intervals. For example, the following lines will generate 8 notches in
the output spectrum, with the notches spaced at octaves of kfreq:

aphs    phaser2    ain, kfreq, 0.5, 8, 2, 2, 0
aout    =          ain + aphs

When imode = 2, the value of ksep must be greater than 0. ksep can be
swept to create a compression and expansion of notch frequencies (with
more dramatic effects than when imode = 1).


===========================================================================
phasor                                                               *phasor*

  Description

Produce a normalized moving phase value.

  Syntax

ares phasor xcps [, iphs]

kres phasor kcps [, iphs]

  Initialization

iphs (optional) -- initial phase, expressed as a fraction of a cycle (0
to 1). A negative value will cause phase initialization to be skipped.
The default value is zero.

  Performance

An internal phase is successively accumulated in accordance with the
kcps or xcps frequency to produce a moving phase value, normalized to
lie in the range 0 <= phs < 1.

When used as the index to a table unit, this phase (multiplied by the
desired function table length) will cause it to behave like an oscillator.

Note that phasor is a special kind of integrator, accumulating phase
increments that represent frequency settings.


===========================================================================
phasorbnk                                                         *phasorbnk*

  Description

Produce an arbitrary number of normalized moving phase values,
accessable by an index.

  Syntax

ares phasorbnk xcps, kndx, icnt [, iphs]

kres phasorbnk kcps, kndx, icnt [, iphs]

  Initialization

icnt -- maximum number of phasors to be used.

iphs -- initial phase, expressed as a fraction of a cycle (0 to 1). If
-1 initialization is skipped. If iphas>1 each phasor will be initialized
with a random value.

  Performance

kndx -- index value to access individual phasors

For each independent phasor, an internal phase is successively
accumulated in accordance with the kcps or xcps frequency to produce a
moving phase value, normalized to lie in the range 0 <= phs < 1. Each
individual phasor is accessed by index kndx.

This phasor bank can be used inside a k-rate loop to generate multiple
independent voices, or together with the adsynt opcode to change
parameters in the tables used by adsynt.


===========================================================================
phs                                                                     *phs*

  Description

This opcode returns the phases of a complex-number array, as a
real-valued array with half the size of its input plus one. The reason
for the extra point is to keep the array size equivalent to the output
of the mags opcode (which is often used alongside this one).

  Syntax

kout[] phs kin[]

  Performance

kout[] -- output array containing the phases. It will be created if it
does not exist.

kin[] -- input array containing the complex-valued real-imaginary input.


===========================================================================
pindex                                                               *pindex*

  Description

pindex returns the value of a specified pfield.

  Syntax

ivalue pindex ipfieldIndex

  Initialization

ipfieldIndex - pfield number to query.

ivalue - value of the pfield.


===========================================================================
pinker                                                               *pinker*

  Description

Generates pink noise (-3dB/oct response) by the New Shade of Pink
algorithm of Stefan Stenzel.

  Syntax

ares pinker

  Performance

pinker generates pink noise (i.e., noise with equal energy in each
octave), by the algorithm of Stefan Stenzel. For details of the
algorithm look at http://stenzel.waldorfmusic.de/post/pink/.


===========================================================================
pinkish                                                             *pinkish*

  Description

Generates approximate pink noise (-3dB/oct response) by one of two
different methods:

  * a multirate noise generator after Moore, coded by Martin Gardner

  * a filter bank designed by Paul Kellet

  Syntax

ares pinkish xin [, imethod] [, inumbands] [, iseed] [, iskip]

  Initialization

imethod (optional, default=0) -- selects filter method:

  * 0 = Gardner method (default).

  * 1 = Kellet filter bank.

  * 2 = A somewhat faster filter bank by Kellet, with less accurate
    response.

inumbands (optional) -- only effective with Gardner method. The number
of noise bands to generate. Maximum is 32, minimum is 4. Higher levels
give smoother spectrum, but above 20 bands there will be almost DC-like
slow fluctuations. Default value is 20.

iseed (optional, default=0) -- only effective with Gardner method. If
non-zero, seeds the random generator. If zero, the generator will be
seeded from current time. Default is 0.

iskip (optional, default=0) -- if non-zero, skip (re)initialization of
internal state (useful for tied notes). Default is 0.

  Performance

xin -- for Gardner method: k- or a-rate amplitude. For Kellet filters:
normally a-rate uniform random noise from rand (31-bit) or unirand, but
can be any a-rate signal. The output peak value varies widely (±15%)
even over long runs, and will usually be well below the input amplitude.
Peak values may also occasionally overshoot input amplitude or noise.

pinkish attempts to generate pink noise (i.e., noise with equal energy
in each octave), by one of two different methods.

The first method, by Moore & Gardner, adds several (up to 32) signals of
white noise, generated at octave rates (sr, sr/2, sr/4 etc). It obtains
pseudo-random values from an internal 32-bit generator. This random
generator is local to each opcode instance and seedable (similar to rand).

The second method is a lowpass filter with a response approximating
-3dB/oct. If the input is uniform white noise, it outputs pink noise.
Any signal may be used as input for this method. The high quality filter
is slower, but has less ripple and a slightly wider operating frequency
range than less computationally intense versions. With the Kellet
filters, seeding is not used.

The Gardner method output has some frequency response anomalies in the
low-mid and high-mid frequency ranges. More low-frequency energy can be
generated by increasing the number of bands. It is also a bit faster.
The refined Kellet filter has very smooth spectrum, but a more limited
effective range. The level increases slightly at the high end of the
spectrum.


===========================================================================
pitch                                                                 *pitch*

  Description

Using the same techniques as spectrum and specptrk, pitch tracks the
pitch of the signal in octave point decimal form, and amplitude in dB.

  Syntax

koct, kamp pitch asig, iupdte, ilo, ihi, idbthresh [, ifrqs] [, iconf] \
      [, istrt] [, iocts] [, iq] [, inptls] [, irolloff] [, iskip]

  Initialization

iupdte -- length of period, in seconds, that outputs are updated

ilo, ihi -- range in which pitch is detected, expressed in octave point
decimal

idbthresh -- amplitude, expressed in decibels, necessary for the pitch
to be detected. Once started it continues until it is 6 dB down.

ifrqs (optional) -- number of divisons of an octave. Default is 12 and
is limited to 120.

iconf (optional) -- the number of conformations needed for an octave
jump. Default is 10.

istrt (optional) -- starting pitch for tracker. Default value is (ilo +
ihi)/2.

iocts (optional) -- number of octave decimations in spectrum. Default is 6.

iq (optional) -- Q of analysis filters. Default is 10.

inptls (optional) -- number of harmonics, used in matching. Computation
time increases with the number of harmonics. Default is 4.

irolloff (optional) -- amplitude rolloff for the set of filters
expressed as fraction per octave. Values must be positive. Default is 0.6.

iskip (optional) -- if non-zero, skips initialization. Default is 0.

  Performance

koct -- The pitch output, given in the octave point decimal format.

kamp -- The amplitude output.

pitch analyzes the input signal, asig, to give a pitch/amplitude pair of
outputs, for the strongest frequency in the signal. The value is updated
every iupdte seconds.

The number of partials and rolloff fraction can effect the pitch
tracking, so some experimentation may be necessary. Suggested values are
4 or 5 harmonics, with rolloff 0.6, up to 10 or 12 harmonics with
rolloff 0.75 for complex timbres, with a weak fundamental.


===========================================================================
pitchamdf                                                         *pitchamdf*

  Description

Follows the pitch of a signal based on the AMDF method (Average
Magnitude Difference Function). Outputs pitch and amplitude tracking
signals. The method is quite fast and should run in realtime. This
technique usually works best for monophonic signals.

  Syntax

kcps, krms pitchamdf asig, imincps, imaxcps [, icps] [, imedi] \
      [, idowns] [, iexcps] [, irmsmedi]

  Initialization

imincps -- estimated minimum frequency (expressed in Hz) present in the
signal

imaxcps -- estimated maximum frequency present in the signal

icps (optional, default=0) -- estimated initial frequency of the signal.
If 0, icps = (imincps+imaxcps) / 2. The default is 0.

imedi (optional, default=1) -- size of median filter applied to the
output kcps. The size of the filter will be imedi*2+1. If 0, no median
filtering will be applied. The default is 1.

idowns (optional, default=1) -- downsampling factor for asig. Must be an
integer. A factor of idowns > 1 results in faster performance, but may
result in worse pitch detection. Useful range is 1 - 4. The default is 1.

iexcps (optional, default=0) -- how frequently pitch analysis is
executed, expressed in Hz. If 0, iexcps is set to imincps. This is
usually reasonable, but experimentation with other values may lead to
better results. Default is 0.

irmsmedi (optional, default=0) -- size of median filter applied to the
output krms. The size of the filter will be irmsmedi*2+1. If 0, no
median filtering will be applied. The default is 0.

  Performance

kcps -- pitch tracking output

krms -- amplitude tracking output

pitchamdf usually works best for monophonic signals, and is quite
reliable if appropriate initial values are chosen. Setting imincps and
imaxcps as narrow as possible to the range of the signal's pitch,
results in better detection and performance.

Because this process can only detect pitch after an initial delay,
setting icps close to the signal's real initial pitch prevents spurious
data at the beginning.

The median filter prevents kcps from jumping. Experiment to determine
the optimum value for imedi for a given signal.

Other initial values can usually be left at the default settings.
Lowpass filtering of asig before passing it to pitchamdf, can improve
performance, especially with complex waveforms.


===========================================================================
planet                                                               *planet*

  Description

planet simulates a planet orbiting in a binary star system. The outputs
are the x, y and z coordinates of the orbiting planet. It is possible
for the planet to achieve escape velocity by a close encounter with a
star. This makes this system somewhat unstable.

  Syntax

ax, ay, az planet kmass1, kmass2, ksep, ix, iy, iz, ivx, ivy, ivz, idelta \
      [, ifriction] [, iskip]

  Initialization

ix, iy, iz -- the initial x, y and z coordinates of the planet

ivx, ivy, ivz -- the initial velocity vector components for the planet.

idelta -- the step size used to approximate the differential equation.

ifriction (optional, default=0) -- a value for friction, which can be
used to keep the system from blowing up

iskip (optional, default=0) -- if non zero skip the initialisation of
the filter. (New in Csound version 4.23f13 and 5.0)

  Performance

ax, ay, az -- the output x, y, and z coodinates of the planet

kmass1 -- the mass of the first star

kmass2 -- the mass of the second star


===========================================================================
platerev                                                           *platerev*

  Description

Models the reverberation of a rectangular metal plate with settable
physical characteristics when excited by audio signal(s).

  Syntax

a1[, a2, ...] platerev itabexcite. itabouts, kbndry, iaspect, istiff, idecay, iloss, aexcite1[, aexcite2, ...]

  Initialization

itabexcite -- number of a table that contains triplets for each
excitation signal, (frequency, radius, initial phase in radians). The
radius should be less than 1. These control where the excitation
happens. The values in the table for frequency and radius may be changed
in performance, with the proviso about clicking if the changes are too
large.

itabouts -- number of a table that contains triplets for each output
signal, (frequency, radius, initial phase in radians). See itabexcite
description.

kbndry -- boundary condition of the plate; 0 = free, 1 = clamped, 2 =
pivoting. Other values are undefined. Thus parameter may be changed at
k-rate but that might give rise to clicks.

iaspect -- plate aspect ratio which should be less than or equal to 1.

istiff -- plate stiffness parameter (set around 1 or less for plate
reverb).

idecay -- time taken for 30 dB decay

iloss -- loss parameter for high-frequency damping (value about 0.001
suggested).

  Performance

A metal plate is excited by a stereo signal and the resulting
reverberation captured.

aexciten -- excitation signal to be inserted into the plate.


===========================================================================
plltrack                                                           *plltrack*

  Description

plltrack, a pitch tracker based on a phase-locked loop algorithm,
described in Zolzer, U, Sankarababu, S.V. and Moller, S, "PLL-based
Pitch Detection and Tracking for Audio Signals. Proc. of IIH-MSP 2012".

  Syntax

acps, alock plltrack asig, kd [, kloopf, kloopq, klf, khf, kthresh]

  Performance

acps -- estimated pitch in Hz.

alock -- phase lock indicator, a phase error indicating the quality of
the tracking, with values between 0 and 1. Higher values indicate good
tracking

kd -- PLL feedback gain, controls frequency range of PLL (between 0 and
1). Higher values increase the range of the tracking.

kloopf -- PLL LP filter cf, controls frequency range of PLL (opt,
defaults to 20Hz).

kloopq -- PLL LP filter Q, controls rise time of FO step (opt, defaults
to 1/3)

klf -- lowest tracking freq (opt, defaults to 20Hz)

khf -- highest tracking freq (opt, defaults to 1500Hz)

kthresh -- tracking signal level threshold (optional, defaults to 0.001,
equiv to -60dBfs)

plltrack analyzes the input signal, asig, estimating the fundamental of
a monophonic signal. Its output is updated every sample.


===========================================================================
pluck                                                                 *pluck*

  Description

Audio output is a naturally decaying plucked string or drum sound based
on the Karplus-Strong algorithms.

  Syntax

ares pluck kamp, kcps, icps, ifn, imeth [, iparm1] [, iparm2]

  Initialization

icps -- intended pitch value in Hz, used to set up a buffer of 1 cycle
of audio samples which will be smoothed over time by a chosen decay
method. icps normally anticipates the value of kcps, but may be set
artificially high or low to influence the size of the sample buffer.

ifn -- table number of a stored function used to initialize the cyclic
decay buffer. If ifn = 0, a random sequence will be used instead.

imeth -- method of natural decay. There are six, some of which use
parameters values that follow.

 1. simple averaging. A simple smoothing process, uninfluenced by
    parameter values.

 2. stretched averaging. As above, with smoothing time stretched by a
    factor of iparm1 (>=1).

 3. simple drum. The range from pitch to noise is controlled by a
    'roughness factor' in iparm1 (0 to 1). Zero gives the plucked string
    effect, while 1 reverses the polarity of every sample (octave down,
    odd harmonics). The setting .5 gives an optimum snare drum.

 4. stretched drum. Combines both roughness and stretch factors. iparm1
    is roughness (0 to 1), and iparm2 the stretch factor (>=1).

 5. weighted averaging. As method 1, with iparm1 weighting the current
    sample (the status quo) and iparm2 weighting the previous adjacent
    one. iparm1 + iparm2 must be <= 1.

 6. 1st order recursive filter, with coefs .5. Unaffected by parameter
    values.

iparm1, iparm2 (optional) -- parameter values for use by the smoothing
algorithms (above). The default values are both 0.

  Performance

kamp -- the output amplitude.

kcps -- the resampling frequency in cycles-per-second.

An internal audio buffer, filled at i-time according to ifn, is
continually resampled with periodicity kcps and the resulting output is
multiplied by kamp. Parallel with the sampling, the buffer is smoothed
to simulate the effect of natural decay.

Plucked strings (1, 2, 5, 6) are best realized by starting with a random
noise source, which is rich in initial harmonics. Drum sounds (methods
3, 4) work best with a flat source (wide pulse), which produces a deep
noise attack and sharp decay.

The original Karplus-Strong algorithm used a fixed number of samples per
cycle, which caused serious quantization of the pitches available and
their intonation. This implementation resamples a buffer at the exact
pitch given by kcps, which can be varied for vibrato and glissando
effects. For low values of the orch sampling rate (e.g. sr = 10000),
high frequencies will store only very few samples (sr / icps). Since
this may cause noticeable noise in the resampling process, the internal
buffer has a minimum size of 64 samples. This can be further enlarged by
setting icps to some artificially lower pitch.


===========================================================================
poisson                                                             *poisson*

  Description

Poisson distribution random number generator (positive values only).
This is an x-class noise generator.

  Syntax

ares poisson klambda

ires poisson klambda

kres poisson klambda

  Performance

ares, kres, ires - number of events occuring (always an integer).

klambda - the expected number of occurrences that occur during the rate
interval.

        Adapted from Wikipedia:

In probability theory and statistics, the Poisson distribution is a
discrete probability distribution. It expresses the probability of a
number of events occurring in a fixed period of time if these events
occur with a known average rate, and are independent of the time since
the last event.

The Poisson distribution describing the probability that there are
exactly k occurrences (k being a non-negative integer, k = 0, 1, 2, ...)
is:

[The Poisson distribution equation.]

where:

  * λ is a positive real number, equal to the expected number of
    occurrences that occur during the given interval. For instance, if
    the events occur on average every 4 minutes, and you are interested
    in the number of events occurring in a 10 minute interval, you would
    use as model a Poisson distribution with λ = 10/4 = 2.5. This
    parameter is called klambda on the poisson opcodes.
  * k refers to the number of i- , k- or a- periods elapsed.

The Poisson distribution arises in connection with Poisson processes. It
applies to various phenomena of discrete nature (that is, those that may
happen 0, 1, 2, 3, ... times during a given period of time or in a given
area) whenever the probability of the phenomenon happening is constant
in time or space. Examples of events that can be modelled as Poisson
distributions include:

  * The number of cars that pass through a certain point on a road
    (sufficiently distant from traffic lights) during a given period of
    time.
  * The number of spelling mistakes one makes while typing a single page.
  * The number of phone calls at a call center per minute.
  * The number of times a web server is accessed per minute.
  * The number of roadkill (animals killed) found per unit length of road.
  * The number of mutations in a given stretch of DNA after a certain
    amount of radiation.
  * The number of unstable nuclei that decayed within a given period of
    time in a piece of radioactive substance. The radioactivity of the
    substance will weaken with time, so the total time interval used in
    the model should be significantly less than the mean lifetime of the
    substance.
  * The number of pine trees per unit area of mixed forest.
  * The number of stars in a given volume of space.
  * The distribution of visual receptor cells in the retina of the human
    eye.
  * The number of viruses that can infect a cell in cell culture.

[A diagram showing the Poisson distribution.]

A diagram showing the Poisson distribution.

For more detailed explanation of these distributions, see:

 1. C. Dodge - T.A. Jerse 1985. Computer music. Schirmer books. pp.265 - 286

 2. D. Lorrain. A panoply of stochastic cannons. In C. Roads, ed. 1989.
    Music machine . Cambridge, Massachusetts: MIT press, pp. 351 - 379.


===========================================================================
pol2rect                                                           *pol2rect*

  Description

Converts an input array in magnitude-phase format to real-imaginary format.

  Syntax

kout[] pol2rect kin[]

kout[] pol2rect kmags[], kphs[]

  Performance

kout[] -- output array containing the complex-valued real-imaginary
output. It will be created if it does not exist.

kin[] -- input array containing the complex-valued magnitude-phase input.

kmags[] -- input array containing the real-valued magnitude input.

kphs[] -- input array containing the real-valued phase input.


===========================================================================
polyaft                                                             *polyaft*

  Description

polyaft returns the polyphonic pressure of the selected note number,
optionally mapped to an user-specified range.

  Syntax

ires polyaft inote [, ilow] [, ihigh]

kres polyaft inote [, ilow] [, ihigh]

  Initialization

inote -- note number. Normally set to the value returned by notnum

ilow (optional, default: 0) -- lowest output value

ihigh (optional, default: 127) -- highest output value

  Performance

kres -- polyphonic pressure (aftertouch).


===========================================================================
polynomial                                                       *polynomial*

  Description

The polynomial opcode calculates a polynomial with a single a-rate input
variable. The polynomial is a sum of any number of terms in the form
kn*x^n where kn is the nth coefficient of the expression. These
coefficients are k-rate values.

  Syntax

aout polynomial ain, k0 [, k1 [, k2 [...]]]

  Performance

ain -- the input signal used as the independent variable of the
polynomial ("x").

aout -- the output signal ("y").

k0, k1, k2, ... -- the coefficients for each term of the polynomial.

If we consider the input parameter ain to be "x" and the output aout to
be "y", then the polynomial opcode calculates the following equation:

        y = k0 + k1*x + k2*x^2 + k3*x^3 + ...


===========================================================================
port                                                                   *port*

  Description

Applies portamento to a step-valued control signal.

  Syntax

kres port ksig, ihtim [, isig]

  Initialization

ihtim -- half-time of the function, in seconds.

isig (optional, default=0) -- initial (i.e. previous) value for internal
feedback. The default value is 0. Negative value will cause
initialization to be skipped and last value from previous instance to be
used as initial value for note.

  Performance

kres -- the output signal at control-rate.

ksig -- the input signal at control-rate.

port applies portamento to a step-valued control signal. At each new
step value, ksig is low-pass filtered to move towards that value at a
rate determined by ihtim. ihtim is the “half-time” of the function (in
seconds), during which the curve will traverse half the distance towards
the new value, then half as much again, etc., theoretically never
reaching its asymptote. With portk, the half-time can be varied at the
control rate.


===========================================================================
portk                                                                 *portk*

  Description

Applies portamento to a step-valued control signal.

  Syntax

kres portk ksig, khtim [, isig]

  Initialization

isig (optional, default=0) -- initial (i.e. previous) value for internal
feedback. The default value is 0.

  Performance

kres -- the output signal at control-rate.

ksig -- the input signal at control-rate.

khtim -- half-time of the function in seconds.

portk is like port except the half-time can be varied at the control rate.


===========================================================================
poscil3                                                             *poscil3*

  Description

High precision oscillator with cubic interpolation.

  Syntax

ares poscil3 aamp, acps [, ifn, iphs]

ares poscil3 aamp, kcps [, ifn, iphs]

ares poscil3 kamp, acps [, ifn, iphs]

ares poscil3 kamp, kcps [, ifn, iphs]

ires poscil3 kamp, kcps [, ifn, iphs]

kres poscil3 kamp, kcps [, ifn, iphs]

  Initialization

ifn -- (optional) function table number. This defaults to -1 which
indicates a sinewave.

iphs (optional, default=0) -- initial phase (normalized table index
0-1). If a negative value is given initialisation of the phase is skipped.

  Performance

ares -- output signal

kamp, aamp -- the amplitude of the output signal.

kcps, acps -- the frequency of the output signal in cycles per second.

poscil3 works like poscil, but uses cubic interpolation.

Note that poscil3 can use defered (non-power of two) length tables.


===========================================================================
poscil                                                               *poscil*

  Description

High precision oscillator.

  Syntax

ares poscil aamp, acps [, ifn, iphs]

ares poscil aamp, kcps [, ifn, iphs]

ares poscil kamp, acps [, ifn, iphs]

ares poscil kamp, kcps [, ifn, iphs]

ires poscil kamp, kcps [, ifn, iphs]

kres poscil kamp, kcps [, ifn, iphs]

  Initialization

ifn -- (optional) function table number. This defaults to -1 which
indicates a sinewave.

iphs (optional, default=0) -- initial phase (normalized table index
0-1). If a negative value is given initialisation of the phase is skipped.

  Performance

ares -- output signal

kamp, aamp -- the amplitude of the output signal.

kcps, acps -- the frequency of the output signal in cycles per second.

poscil (precise oscillator) is the same as oscili, but allows much more
precise frequency control, especially when using long tables and low
frequency values. It uses floating-point table indexing, instead of
integer math, like oscil and oscili. It is only a bit slower than oscili.

Since Csound 4.22, poscil can accept also negative frequency values and
use a-rate values both for amplitude and frequency. So both AM and FM
are allowed using this opcode.

The opcode poscil3 is the same as poscil, but uses cubic interpolation.

Note that poscil can use deffered (non-power of two) length tables.


===========================================================================
pow                                                                     *pow*

  Description

Computes xarg to the power of kpow (or ipow) and scales the result by
inorm.

  Syntax

ares pow aarg, kpow [, inorm]

ires pow iarg, ipow [, inorm]

kres pow karg, kpow [, inorm]

  Initialization

inorm (optional, default=1) -- The number to divide the result (default
to 1). This is especially useful if you are doing powers of a- or k-
signals where samples out of range are extremely common!

  Performance

aarg, iarg, karg -- the base.

ipow, kpow -- the exponent.

  Note

Use ^ with caution in arithmetical statements, as the precedence may not
be correct. New in Csound version 3.493.


===========================================================================
powershape                                                       *powershape*

  Description

The powershape opcode raises an input signal to a power with pre- and
post-scaling of the signal so that the output will be in a predictable
range. It also processes negative inputs in a symmetrical way to
positive inputs, calculating a dynamic transfer function that is useful
for waveshaping.

  Syntax

aout powershape ain, kShapeAmount [, ifullscale]

  Initialization

ifullscale -- optional parameter specifying the range of input values
from -ifullscale to ifullscale. Defaults to 1.0 -- you should set this
parameter to the maximum expected input value.

  Performance

ain -- the input signal to be shaped.

aout -- the output signal.

kShapeAmount -- the amount of the shaping effect applied to the input;
equal to the power that the input signal is raised.

The powershape opcode is very similar to the pow unit generators for
calculating the mathematical "power of" operation. However, it
introduces a couple of twists that can make it much more useful for
waveshaping audio-rate signals. The kShapeAmount parameter is the
exponent to which the input signal is raised.

To avoid discontinuities, the powershape opcode treats all input values
as positive (by taking their absolute value) but preserves their
original sign in the output signal. This allows for smooth shaping of
any input signal while varying the exponent over any range. (powershape
also (hopefully) deals intelligently with discontinuities that could
arise when the exponent and input are both zero. Note though that
negative exponents will usually cause the signal to exceed the maximum
amplitude specified by the ifullscale parameter and should normally be
avoided).

The other adaptation involves the ifullscale parameter. The input signal
is divided by ifullscale before being raised to kShapeAmount and then
multiplied by ifullscale before being output. This normalizes the input
signal to the interval [-1,1], guaranteeing that the output (before
final scaling) will also be within this range for positive shaping
amounts and providing a smoothly evolving transfer function while
varying the amount of shaping. Values of kShapeAmount between (0,1) will
make the signal more "convex" while values greater than 1 will make it
more "concave". A value of exactly 1.0 will produce no change in the
input signal.


===========================================================================
powoftwo                                                           *powoftwo*

  Description

Performs a power-of-two calculation.

  Syntax

powoftwo(x)  (init-rate or control-rate args only)

  Performance

powoftwo() function returns 2^x and allows positive and negatives
numbers as argument. The range of values admitted in powoftwo() is -5 to
+5 allowing a precision more fine than one cent in a range of ten
octaves. If a greater range of values is required, use the slower opcode
pow.

These functions are fast, because they read values stored in tables.
Also they are very useful when working with tuning ratios. They work at
i- and k-rate.


===========================================================================
prealloc                                                           *prealloc*

  Description

Creates space for instruments but does not run them.

  Syntax

prealloc insnum, icount

prealloc "insname", icount

  Initialization

insnum -- instrument number

icount -- number of instrument allocations

“insname” -- A string (in double-quotes) representing a named instrument.

  Performance

All instances of prealloc must be defined in the header section, not in
the instrument body.


===========================================================================
prepiano                                                           *prepiano*

  Description

Audio output is a tone similar to a piano string, prepared with a number
of rubbers and rattles. The method uses a physical model developed from
solving the partial differential equation.

  Syntax

ares prepiano ifreq, iNS, iD, iK, \
    iT30,iB, kbcl, kbcr, imass, ihvfreq, iinit, ipos, ivel, isfreq, \
    isspread[, irattles, irubbers]

al,ar prepiano ifreq, iNS, iD, iK, \
    iT30,iB, kbcl, kbcr, imass, ihvfreq, iinit, ipos, ivel, isfreq, \
    isspread[, irattles, irubbers]

  Initialization

ifreq -- The base frequency of the string.

iNS -- the number of strings involved. In a real piano 1, 2 or 3 strings
are found in different frequency regions.

iD -- the amount each string other that the first is detuned from the
main frequency, measured in cents.

iK -- dimensionless stiffness parameter.

iT30 -- 30 db decay time in seconds.

ib -- high-frequency loss parameter (keep this small).

imass -- the mass of the piano hammer.

ihvfreq -- the frequency of the natural vibrations of the hammer.

iinit -- the initial position of the hammer.

ipos -- position along the string that the strike occurs.

ivel -- normalized strike velocity.

isfreq -- scanning frequency of the reading place.

isspread -- scanning frequency spread.

irattles -- table number giving locations of any rattle(s).

irubbers -- table number giving locations of any rubbers(s).

The rattles and rubbers tables are collections of four values, preceeded
by a count. In the case of a rattle the four are position, mass density
ratio of rattle/string, frequency of rattle and vertical length of the
rattle. For the rubber the fours are position, mass density ratio of
rubber/string, frequency of rubber and the loss parameter.

  Performance

A note is played on a piano string, with the arguments as below.

kbcL -- Boundary condition at left end of string (1 is clamped, 2
pivoting and 3 free).

kbcR -- Boundary condition at right end of string (1 is clamped, 2
pivoting and 3 free).

Note that changing the boundary conditions during playing may lead to
glitches and is made available as an experiment.


===========================================================================
print                                                                 *print*

  Description

These units will print orchestra init-values.

  Syntax

print iarg [, iarg1] [, iarg2] [...]

  Initialization

iarg, iarg2, ... -- i-rate arguments.

  Performance

print -- print the current value of the i-time arguments (or
expressions) iarg at every i-pass through the instrument.

  Note

The print opcode will truncate decimal places and may not show the
complete value. Csound's precision depends on whether it is the floats
(32-bit) or double (64-bit) version, since most internal calculations
use one of these formats. If you need more resolution in the console
output, you can try printf.


===========================================================================
printf                                                               *printf*

  Description

printf and printf_i write formatted output, similarly to the C function
printf(). printf_i runs at i-time only, while printf runs both at
initialization and performance time.

  Syntax

printf_i Sfmt, itrig, [iarg1[, iarg2[, ... ]]]

printf Sfmt, ktrig, [xarg1[, xarg2[, ... ]]]

  Initialization

Sfmt -- format string, has the same format as in printf() and other
similar C functions, except length modifiers (l, ll, h, etc.) are not
supported. The following conversion specifiers are allowed:

  * d, i, o, u, x, X, e, E, f, F, g, G, c, s

iarg1, iarg2, ... -- input arguments (max. 30) for format. Integer
formats like %d round the input values to the nearest integer.

itrig -- if greater than zero the opcode performs the printing;
otherwise it is an null operation.

  Performance

ktrig -- if greater than zero and different from the value on the
previous control cycle the opcode performs the requested printing.
Initially this previous value is taken as zero.

xarg1, xarg2, ... -- input arguments (max. 30) for format. Integer
formats like %d round the input values to the nearest integer. Note that
only k-rate and i-rate arguments are valid (no a-rate printing)


===========================================================================
printk2                                                             *printk2*

  Description

Prints a new value every time a control variable changes.

  Syntax

printk2 kvar [, inumspaces]

  Initialization

inumspaces (optional, default=0) -- number of space characters printed
before the value of kvar

  Performance

kvar -- signal to be printed

Derived from Robin Whittle's printk, prints a new value of kvar each
time kvar changes. Useful for monitoring MIDI control changes when using
sliders.

  Warning

WARNING! Don't use this opcode with normal, continuously variant
k-signals, because it can hang the computer, as the rate of printing is
too fast.


===========================================================================
printk                                                               *printk*

  Description

Prints one k-rate value at specified intervals.

  Syntax

printk itime, kval [, ispace]

  Initialization

itime -- time in seconds between printings.

ispace (optional, default=0) -- number of spaces to insert before
printing. (default: 0, max: 130)

  Performance

kval -- The k-rate values to be printed.

printk prints one k-rate value on every k-cycle, every second or at
intervals specified. First the instrument number is printed, then the
absolute time in seconds, then a specified number of spaces, then the
kval value. The variable number of spaces enables different values to be
spaced out across the screen - so they are easier to view.

This opcode can be run on every k-cycle it is run in the instrument. To
every accomplish this, set itime to 0.

When itime is not 0, the opcode print on the first k-cycle it is called,
and subsequently when every itime period has elapsed. The time cycles
start from the time the opcode is initialized - typically the
initialization of the instrument.


===========================================================================
printks                                                             *printks*

  Description

Prints at k-rate using a printf() style syntax.

  Syntax

printks "string", itime [, kval1] [, kval2] [...]

  Initialization

"string" -- the text string to be printed. Can be up to 8192 characters
and must be in double quotes.

itime -- time in seconds between printings.

  Performance

kval1, kval2, ... (optional) -- The k-rate values to be printed. These
are specified in “string” with the standard C value specifier (%f, %d,
etc.) in the order given.

In Csound version 4.23, you can use as many kval variables as you like.
In versions prior to 4.23, you must specify 4 and only 4 kvals (using 0
for unused kvals).

printks prints numbers and text which can be i-time or k-rate values.
printks is highly flexible, and if used together with cursor positioning
codes, could be used to write specific values to locations in the screen
as the Csound processing proceeds.

A special mode of operation allows this printks to convert kval1 input
parameter into a 0 to 255 value and to use it as the first character to
be printed. This enables a Csound program to send arbitrary characters
to the console. To achieve this, make the first character of the string
a # and then, if desired continue with normal text and format specifiers.

This opcode can be run on every k-cycle it is run in the instrument. To
every accomplish this, set itime to 0.

When itime is not 0, the opcode print on the first k-cycle it is called,
and subsequently when every itime period has elapsed. The time cycles
start from the time the opcode is initialized - typically the
initialization of the instrument.

Print Output Formatting

All standard C language printf() control characters may be used. For
example, if kval1 = 153.26789 then some common formatting options are:

 1. %f prints with full precision: 153.26789

 2. %5.2f prints: 153.26

 3. %d prints integers-only: 153

 4. %c treats kval1 as an ascii character code.

In addition to all the printf() codes, printks supports these useful
character codes:

printks Code    Character Code
\\r, \\R, %r, or %R     return character (\r)
\\n, \\N, %n, %N        newline character (\n)
\\t, \\T, %t, or %T     tab character (\t)
%!      semicolon character (;) This was needed because a “;” is interpreted
as an comment.
^       escape character (0x1B)
^ ^     caret character (^)
˜       ESC[ (escape+[ is the escape sequence for ANSI consoles)
˜˜      tilde (˜)

For more information about printf() formatting, consult any C language
documentation.

  Note

Prior to version 4.23, only the %f format code was supported.


===========================================================================
printks2                                                           *printks2*

  Description

Prints a new value every time a control variable changes using a
printf() style syntax.

  Syntax

printks2 "string", kval

  Initialization

"string" -- the text string to be used as a format.

  Performance

kval -- signal to be printed. The style of printing is specified in
“string” with the standard C value specifier (%f, %d, etc.).

Print Output Formatting

All standard C language printf() control characters may be used. For
example, if kval1 = 153.26789 then some common formatting options are:

 1. %f prints with full precision: 153.26789

 2. %5.2f prints: 153.26

 3. %d prints integers-only: 153

 4. %c treats kval1 as an ascii character code.

In addition to all the printf() codes, printks2 supports these useful
character codes:

printks2 Code   Character Code
\\r, \\R, %r, or %R     return character (\r)
\\n, \\N, %n, %N        newline character (\n)
\\t, \\T, %t, or %T     tab character (\t)
%!      semicolon character (;) This was needed because a “;” is interpreted
as an comment.
^       escape character (0x1B)
^ ^     caret character (^)
˜       ESC[ (escape+[ is the escape sequence for ANSI consoles)
˜˜      tilde (˜)

For more information about printf() formatting, consult any C language
documentation.


===========================================================================
prints                                                               *prints*

  Description

Prints at init-time using a printf() style syntax.

  Syntax

prints "string" [, kval1] [, kval2] [...]

  Initialization

"string" -- the text string to be printed. Can be up to 8192 characters
and must be in double quotes.

  Performance

kval1, kval2, ... (optional) -- The k-rate values to be printed. These
are specified in “string” with the standard C value specifier (%f, %d,
etc.) in the order given. Use 0 for those which are not used.

prints is similar to the printks opcode except it operates at init-time
instead of k-rate. For more information about output formatting, please
look at printks's documentation.


===========================================================================
product                                                             *product*

  Description

Multiplies any number of a-rate signals.

  Syntax

ares product asig1, asig2 [, asig3] [...]

  Performance

asig1, asig2, asig3, ... -- a-rate signals to be multiplied.


===========================================================================
pset                                                                   *pset*

  Description

Defines and initializes numeric arrays at orchestra load time.

  Syntax

pset icon1 [, icon2] [...]

  Initialization

icon1, icon2, ... -- preset values for a MIDI instrument

pset (optional) defines and initializes numeric arrays at orchestra load
time. It may be used as an orchestra header statement (i.e. instrument
0) or within an instrument. When defined within an instrument, it is not
part of its i-time or performance operation, and only one statement is
allowed per instrument. These values are available as i-time defaults.
When an instrument is triggered from MIDI it only gets p1 and p2 from
the event, and p3, p4, etc. will receive the actual preset values.


===========================================================================
ptable                                                               *ptable*

  Description

Accesses table values by direct indexing.

  Syntax

ares ptable andx, ifn [, ixmode] [, ixoff] [, iwrap]

ires ptable indx, ifn [, ixmode] [, ixoff] [, iwrap]

kres ptable kndx, ifn [, ixmode] [, ixoff] [, iwrap]

  Initialization

ifn -- function table number.

ixmode (optional) -- index data mode. The default value is 0.

  * 0 = raw index

  * 1 = normalized (0 to 1)

ixoff (optional) -- amount by which index is to be offset. For a table
with origin at center, use tablesize/2 (raw) or .5 (normalized). The
default value is 0.

iwrap (optional) -- wraparound index flag. The default value is 0.

  * 0 = nowrap (index < 0 treated as index=0; index > tablesize sticks
    at index=size)

  * 1 = wraparound.

  Performance

ptable invokes table lookup on behalf of init, control or audio indices.
These indices can be raw entry numbers (0, 1, 2,... size - 1) or scaled
values (0 to 1). Indices are first modified by the offset value then
checked for range before table lookup (see iwrap). If index is likely to
be full scale, or if interpolation is being used, the table should have
an extended guard point. table indexed by a periodic phasor ( see
phasor) will simulate an oscillator.


===========================================================================
ptablei                                                             *ptablei*

  Description

Accesses table values by direct indexing with linear interpolation.

  Syntax

ares ptablei andx, ifn [, ixmode] [, ixoff] [, iwrap]

ires ptablei indx, ifn [, ixmode] [, ixoff] [, iwrap]

kres ptablei kndx, ifn [, ixmode] [, ixoff] [, iwrap]

  Initialization

ifn -- function table number. The table need not be a power of 2 long.

ixmode (optional) -- index data mode. The default value is 0.

  * 0 = raw index

  * 1 = normalized (0 to 1)

ixoff (optional) -- amount by which index is to be offset. For a table
with origin at center, use tablesize/2 (raw) or .5 (normalized). The
default value is 0.

iwrap (optional) -- wraparound index flag. The default value is 0.

  * 0 = nowrap (index < 0 treated as index=0; index > tablesize sticks
    at index=size)

  * 1 = wraparound.

  Performance

ptablei is a interpolating unit in which the fractional part of index is
used to interpolate between adjacent table entries. The smoothness
gained by interpolation is at some small cost in execution time (see
also oscili, etc.), but the interpolating and non-interpolating units
are otherwise interchangeable.


===========================================================================
ptable3                                                             *ptable3*

  Description

Accesses table values by direct indexing with cubic interpolation.

  Syntax

ares ptable3 andx, ifn [, ixmode] [, ixoff] [, iwrap]

ires ptable3 indx, ifn [, ixmode] [, ixoff] [, iwrap]

kres ptable3 kndx, ifn [, ixmode] [, ixoff] [, iwrap]

  Initialization

ifn -- function table number.

ixmode (optional) -- index data mode. The default value is 0.

  * 0 = raw index

  * 1 = normalized (0 to 1)

ixoff (optional) -- amount by which index is to be offset. For a table
with origin at center, use tablesize/2 (raw) or .5 (normalized). The
default value is 0.

iwrap (optional) -- wraparound index flag. The default value is 0.

  * 0 = nowrap (index < 0 treated as index=0; index > tablesize sticks
    at index=size)

  * 1 = wraparound.

  Performance

ptable3 is identical to table3, except that it uses does not require the
table to have a power of two size.


===========================================================================
ptablew                                                             *ptablew*

  Description

This opcode operates on existing function tables, changing their
contents. ptablew is for writing at k- or at a-rates, with the table
number being specified at init time. Using ptablew with i-rate signal
and index values is allowed, but the specified data will always be
written to the function table at k-rate, not during the initialization
pass. The valid combinations of variable types are shown by the first
letter of the variable names.

  Syntax

ptablew asig, andx, ifn [, ixmode] [, ixoff] [, iwgmode]

ptablew isig, indx, ifn [, ixmode] [, ixoff] [, iwgmode]

ptablew ksig, kndx, ifn [, ixmode] [, ixoff] [, iwgmode]

  Initialization

asig, isig, ksig -- The value to be written into the table.

andx, indx, kndx -- Index into table, either a positive number range
matching the table length (ixmode = 0) or a 0 to 1 range (ixmode != 0)

ifn -- Table number. Must be >= 1. Floats are rounded down to an
integer. If a table number does not point to a valid table, or the table
has not yet been loaded (GEN01) then an error will result and the
instrument will be de-activated.

ixmode (optional, default=0) -- index mode.

  * 0 = xndx and ixoff ranges match the length of the table.

  * !=0 = xndx and ixoff have a 0 to 1 range.

ixoff (optional, default=0) -- index offset.

  * 0 = Total index is controlled directly by xndx, i.e. the indexing
    starts from the start of the table.

  * !=0 = Start indexing from somewhere else in the table. Value must be
    positive and less than the table length (ixmode = 0) or less than 1
    (ixmode != 0).

iwgmode (optional, default=0) -- Wrap and guardpoint mode.

  * 0 = Limit mode.

  * 1 = Wrap mode.

  * 2 = Guardpoint mode.

  Performance

      Limit mode (0)

Limit the total index (ndx + ixoff) to between 0 and the guard point.
For a table of length 5, this means that locations 0 to 3 and location 4
(the guard point) can be written. A negative total index writes to
location 0.

      Wrap mode (1)

Wrap total index value into locations 0 to E, where E is one less than
the table length. For example, wrap into a 0 to 3 range - so that total
index 6 writes to location 2.

      Guardpoint mode (2)

The guardpoint is written at the same time as location 0 is written -
with the same value.

This facilitates writing to tables which are intended to be read with
interpolation for producing smooth cyclic waveforms. In addition, before
it is used, the total index is incremented by half the range between one
location and the next, before being rounded down to the integer address
of a table location.

Normally (igwmode = 0 or 1) for a table of length 5 - which has
locations 0 to 3 as the main table and location 4 as the guard point, a
total index in the range of 0 to 0.999 will write to location 0.
("0.999" means just less than 1.0.) 1.0 to 1.999 will write to location
1 etc. A similar pattern holds for all total indexes 0 to 4.999 (igwmode
= 0) or to 3.999 (igwmode = 1). igwmode = 0 enables locations 0 to 4 to
be written - with the guardpoint (4) being written with a potentially
different value from location 0.

With a table of length 5 and the iwgmode = 2, then when the total index
is in the range 0 to 0.499, it will write to locations 0 and 4. Range
0.5 to 1.499 will write to location 1 etc. 3.5 to 4.0 will also write to
locations 0 and 4.

This way, the writing operation most closely approximates the results of
interpolated reading. Guard point mode should only be used with tables
that have a guardpoint.

Guardpoint mode is accomplished by adding 0.5 to the total index,
rounding to the next lowest integer, wrapping it modulo the factor of
two which is one less than the table length, writing the table
(locations 0 to 3 in our example) and then writing to the guard point if
index = 0.

ptablew has no output value. The last three parameters are optional and
have default values of 0.

      Caution with k-rate table numbers

At k-rate or a-rate, if a table number of < 1 is given, or the table
number points to a non-existent table, or to one which has a length of 0
(it is to be loaded from a file later) then an error will result and the
instrument will be deactivated. kfn and afn must be initialized at the
appropriate rate using init. Attempting to load an i-rate value into kfn
or afn will result in an error.

  Warning

Note that ptablew is always a k-rate opcode. This means that even its
i-rate version runs at k-rate and will write the value of the i-rate
variable. For this reason, the following code will not work as expected:

<CsoundSynthesizer>
<CsOptions>
</CsOptions>
<CsInstruments>
giFt ftgen  1, 0, 8, 2, 0
instr 1
indx = 0
     ptablew 10, indx, giFt
ival tab_i  indx, giFt
     print  ival
endin
</CsInstruments>
<CsScore>
i 1 0 1
</CsScore>
</CsoundSynthesizer>

Although it may seem this program should print a 10 to the console. It
will print 0, because tab_i will read the value at the initialization of
the note, before the first performance pass, when ptablew writes its value.


===========================================================================
ptrack                                                               *ptrack*

  Description

ptrack takes an input signal, splits it into ihopsize blocks and using a
STFT method, extracts an estimated pitch for its fundamental frequency
as well as estimating the total amplitude of the signal in dB, relative
to full-scale (0dB). The method implies an analysis window size of
2*ihopsize samples (overlaping by 1/2 window), which has to be a
power-of-two, between 128 and 8192 (hopsizes between 64 and 4096).
Smaller windows will give better time precision, but worse frequency
accuracy (esp. in low fundamentals).This opcode is based on an original
algorithm by M. Puckette.

  Syntax

kcps, kamp ptrack asig, ihopsize[,ipeaks]

  Initialization

ihopsize -- size of the analysis 'hop', in samples, required to be
power-of-two (min 64, max 4096). This is the period between measurements.

ipeaks, ihi -- number of spectral peaks to use in the analysis, defaults
to 20 (optional)

  Performance

kcps -- estimated pitch in Hz.

kamp -- estimated amplitude in dB relative to full-scale (0dB) (ie.
always <= 0).

ptrack analyzes the input signal, asig, to give a pitch/amplitude pair
of outputs, for the fundamental of a monophonic signal. The output is
updated every sr/ihopsize seconds.


===========================================================================
puts                                                                   *puts*

  Description

puts prints a string with an optional newline at the end whenever the
trigger signal is positive and changes.

  Syntax

puts Sstr, ktrig[, inonl]

  Initialization

Sstr -- string to be printed

inonl (optional, defaults to 0) -- if non-zero, disables the default
printing of a newline character at the end of the string

  Performance

ktrig -- trigger signal, should be valid at i-time. The string is
printed at initialization time if ktrig is positive, and at performance
time whenever ktrig is both positive and different from the previous
value. Use a constant value of 1 to print once at note initialization.


===========================================================================
pvadd                                                                 *pvadd*

  Description

pvadd reads from a pvoc file and uses the data to perform additive
synthesis using an internal array of interpolating oscillators. The user
supplies the wave table (usually one period of a sine wave), and can
choose which analysis bins will be used in the re-synthesis.

  Syntax

ares pvadd ktimpnt, kfmod, ifilcod, ifn, ibins [, ibinoffset] \
      [, ibinincr] [, iextractmode] [, ifreqlim] [, igatefn]

  Initialization

ifilcod -- integer or character-string denoting a control-file derived
from pvanal analysis of an audio signal. An integer denotes the suffix
of a file pvoc.m; a character-string (in double quotes) gives a
filename, optionally a full pathname. If not fullpath, the file is
sought first in the current directory, then in the one given by the
environment variable SADIR (if defined). pvoc control files contain data
organized for fft resynthesis. Memory usage depends on the size of the
files involved, which are read and held entirely in memory during
computation but are shared by multiple calls (see also lpread).

ifn -- table number of a stored function containing a sine wave.

ibins -- number of bins that will be used in the resynthesis (each bin
counts as one oscillator in the re-synthesis)

ibinoffset (optional) -- is the first bin used (it is optional and
defaults to 0).

ibinincr (optional) -- sets an increment by which pvadd counts up from
ibinoffset for ibins components in the re-synthesis (see below for a
further explanation).

iextractmode (optional) -- determines if spectral extraction will be
carried out and if so whether components that have changes in frequency
below ifreqlim or above ifreqlim will be discarded. A value for
iextractmode of 1 will cause pvadd to synthesize only those components
where the frequency difference between analysis frames is greater than
ifreqlim. A value of 2 for iextractmode will cause pvadd to synthesize
only those components where the frequency difference between frames is
less than ifreqlim. The default values for iextractmode and ifreqlim are
0, in which case a simple resynthesis will be done. See examples below.

igatefn (optional) -- is the number of a stored function which will be
applied to the amplitudes of the analysis bins before resynthesis takes
place. If igatefn is greater than 0 the amplitudes of each bin will be
scaled by igatefn through a simple mapping process. First, the
amplitudes of all of the bins in all of the frames in the entire
analysis file are compared to determine the maximum amplitude value.
This value is then used create normalized amplitudes as indeces into the
stored function igatefn. The maximum amplitude will map to the last
point in the function. An amplitude of 0 will map to the first point in
the function. Values between 0 and 1 will map accordingly to points
along the function table.This will be made clearer in the examples below.

  Performance

ktimpnt and kfmod are used in the same way as in pvoc.


===========================================================================
pvbufread                                                         *pvbufread*

  Description

pvbufread reads from a pvoc file and makes the retrieved data available
to any following pvinterp and pvcross units that appear in an instrument
before a subsequent pvbufread (just as lpread and lpreson work
together). The data is passed internally and the unit has no output of
its own.

  Syntax

pvbufread ktimpnt, ifile

  Initialization

ifile -- the pvoc number (n in pvoc.n) or the name in quotes of the
analysis file made using pvanal. (See pvoc.)

  Performance

ktimpnt -- the passage of time, in seconds, through this file. ktimpnt
must always be positive, but can move forwards or backwards in time, be
stationary or discontinuous, as a pointer into the analysis file.


===========================================================================
pvcross                                                             *pvcross*

  Description

pvcross applies the amplitudes from one phase vocoder analysis file to
the data from a second file and then performs the resynthesis. The data
is passed, as described above, from a previously called pvbufread unit.
The two k-rate amplitude arguments are used to scale the amplitudes of
each files separately before they are added together and used in the
resynthesis (see below for further explanation). The frequencies of the
first file are not used at all in this process. This unit simply allows
for cross-synthesis through the application of the amplitudes of the
spectra of one signal to the frequencies of a second signal. Unlike
pvinterp, pvcross does allow for the use of the ispecwp as in pvoc and
vpvoc.

  Syntax

ares pvcross ktimpnt, kfmod, ifile, kampscale1, kampscale2 [, ispecwp]

  Initialization

ifile -- the pvoc number (n in pvoc.n) or the name in quotes of the
analysis file made using pvanal. (See pvoc.)

ispecwp (optional, default=0) -- if non-zero, attempts to preserve the
spectral envelope while its frequency content is varied by kfmod. The
default value is zero.

  Performance

ktimpnt -- the passage of time, in seconds, through this file. ktimpnt
must always be positive, but can move forwards or backwards in time, be
stationary or discontinuous, as a pointer into the analysis file.

kfmod -- a control-rate transposition factor: a value of 1 incurs no
transposition, 1.5 transposes up a perfect fifth, and 0.5 down an octave.

kampscale1, kampscale2 -- used to scale the amplitudes stored in each
frame of the phase vocoder analysis file. kampscale1 scale the
amplitudes of the data from the file read by the previously called
pvbufread. kampscale2 scale the amplitudes of the file named by ifile.

By using these arguments, it is possible to adjust these values before
applying the interpolation. For example, if file1 is much louder than
file2, it might be desirable to scale down the amplitudes of file1 or
scale up those of file2 before interpolating. Likewise one can adjust
the frequencies of each to bring them more in accord with one another
(or just the opposite, of course!) before the interpolation is performed.


===========================================================================
pvinterp                                                           *pvinterp*

  Description

pvinterp interpolates between the amplitudes and frequencies, on a bin
by bin basis, of two phase vocoder analysis files (one from a previously
called pvbufread unit and the other from within its own argument list),
allowing for user defined transitions between analyzed sounds. It also
allows for general scaling of the amplitudes and frequencies of each
file separately before the interpolated values are calculated and sent
to the resynthesis routines. The kfmod argument in pvinterp performs its
frequency scaling on the frequency values after their derivation from
the separate scaling and subsequent interpolation is performed so that
this acts as an overall scaling value of the new frequency components.

  Syntax

ares pvinterp ktimpnt, kfmod, ifile, kfreqscale1, kfreqscale2, \
      kampscale1, kampscale2, kfreqinterp, kampinterp

  Initialization

ifile -- the pvoc number (n in pvoc.n) or the name in quotes of the
analysis file made using pvanal. (See pvoc.)

  Performance

ktimpnt -- the passage of time, in seconds, through this file. ktimpnt
must always be positive, but can move forwards or backwards in time, be
stationary or discontinuous, as a pointer into the analysis file.

kfmod -- a control-rate transposition factor: a value of 1 incurs no
transposition, 1.5 transposes up a perfect fifth, and .5 down an octave.

kfreqscale1, kfreqscale2, kampscale1, kampscale2 -- used in pvinterp to
scale the frequencies and amplitudes stored in each frame of the phase
vocoder analysis file. kfreqscale1 and kampscale1 scale the frequencies
and amplitudes of the data from the file read by the previously called
pvbufread (this data is passed internally to the pvinterp unit).
kfreqscale2 and kampscale2 scale the frequencies and amplitudes of the
file named by ifile in the pvinterp argument list and read within the
pvinterp unit.

By using these arguments, it is possible to adjust these values before
applying the interpolation. For example, if file1 is much louder than
file2, it might be desirable to scale down the amplitudes of file1 or
scale up those of file2 before interpolating. Likewise one can adjust
the frequencies of each to bring them more in accord with one another
(or just the opposite, of course!) before the interpolation is performed.

kfreqinterp, kampinterp -- used in pvinterp, determine the interpolation
distance between the values of one phase vocoder file and the values of
a second file. When the value of kfreqinterp is 1, the frequency values
will be entirely those from the first file (read by the pvbufread), post
scaling by the kfreqscale1 argument. When the value of kfreqinterp is 0
the frequency values will be those of the second file (read by the
pvinterp unit itself), post scaling by kfreqscale2. When kfreqinterp is
between 0 and 1 the frequency values will be calculated, on a bin, by
bin basis, as the percentage between each pair of frequencies (in other
words, kfreqinterp=0.5 will cause the frequencies values to be half way
between the values in the set of data from the first file and the set of
data from the second file).

kampinterp works in the same way upon the amplitudes of the two files.
Since these are k-rate arguments, the percentages can change over time
making it possible to create many kinds of transitions between sounds.


===========================================================================
pvoc                                                                   *pvoc*

  Description

Implements signal reconstruction using an fft-based phase vocoder.

  Syntax

ares pvoc ktimpnt, kfmod, ifilcod [, ispecwp] [, iextractmode] \
      [, ifreqlim] [, igatefn]

  Initialization

ifilcod -- integer or character-string denoting a control-file derived
from analysis of an audio signal. An integer denotes the suffix of a
file pvoc.m; a character-string (in double quotes) gives a filename,
optionally a full pathname. If not fullpath, the file is sought first in
the current directory, then in the one given by the environment variable
SADIR (if defined). pvoc control contains breakpoint amplitude and
frequency envelope values organized for fft resynthesis. Memory usage
depends on the size of the files involved, which are read and held
entirely in memory during computation but are shared by multiple calls
(see also lpread).

ispecwp (optional) -- if non-zero, attempts to preserve the spectral
envelope while its frequency content is varied by kfmod. The default
value is zero.

iextractmode (optional) -- determines if spectral extraction will be
carried out and if so whether components that have changes in frequency
below ifreqlim or above ifreqlim will be discarded. A value for
iextractmode of 1 will cause pvoc to synthesize only those components
where the frequency difference between analysis frames is greater than
ifreqlim. A value of 2 for iextractmode will cause pvoc to synthesize
only those components where the frequency difference between frames is
less than ifreqlim. The default values for iextractmode and ifreqlim are
0, in which case a simple resynthesis will be done. See examples under
pvadd for how to use spectral extraction.

igatefn (optional) -- the number of a stored function which will be
applied to the amplitudes of the analysis bins before resynthesis takes
place. If igatefn is greater than 0 the amplitudes of each bin will be
scaled by igatefn through a simple mapping process. First, the
amplitudes of all of the bins in all of the frames in the entire
analysis file are compared to determine the maximum amplitude value.
This value is then used create normalized amplitudes as indeces into the
stored function igatefn. The maximum amplitude will map to the last
point in the function. An amplitude of 0 will map to the first point in
the function. Values between 0 and 1 will map accordingly to points
along the function table. See examples under pvadd for how to use
amplitude gating.

  Performance

ktimpnt -- The passage of time, in seconds, through the analysis file.
ktimpnt must always be positive, but can move forwards or backwards in
time, be stationary or discontinuous, as a pointer into the analysis file.

kfmod -- a control-rate transposition factor: a value of 1 incurs no
transposition, 1.5 transposes up a perfect fifth, and .5 down an octave.

pvoc implements signal reconstruction using an fft-based phase vocoder.
The control data stems from a precomputed analysis file with a known
frame rate.

This implementation of pvoc was orignally written by Dan Ellis. It is
based in part on the system of Mark Dolson, but the pre-analysis concept
is new. The spectral extraction and amplitude gating (new in Csound
version 3.56) were added by Richard Karpen based on functions in
SoundHack by Tom Erbe.


===========================================================================
pvread                                                               *pvread*

  Description

pvread reads from a pvoc file and returns the frequency and amplitude
from a single analysis channel or bin. The returned values can be used
anywhere else in the Csound instrument. For example, one can use them as
arguments to an oscillator to synthesize a single component from an
analyzed signal or a bank of pvreads can be used to resynthesize the
analyzed sound using additive synthesis by passing the frequency and
magnitude values to a bank of oscillators.

  Syntax

kfreq, kamp pvread ktimpnt, ifile, ibin

  Initialization

ifile -- the pvoc number (n in pvoc.n) or the name in quotes of the
analysis file made using pvanal. (See pvoc.)

ibin -- the number of the analysis channel from which to return
frequency in Hz and magnitude.

  Performance

kfreq, kamp -- outputs of the pvread unit. These values, retrieved from
a phase vocoder analysis file, represent the values of frequency and
amplitude from a single analysis channel specified in the ibin argument.
Interpolation between analysis frames is performed at k-rate resolution
and dependent of course upon the rate and direction of ktimpnt.

ktimpnt -- the passage of time, in seconds, through this file. ktimpnt
must always be positive, but can move forwards or backwards in time, be
stationary or discontinuous, as a pointer into the analysis file.


===========================================================================
pvsadsyn                                                           *pvsadsyn*

  Description

Resynthesize using a fast oscillator-bank.

  Syntax

ares pvsadsyn fsrc, inoscs, kfmod [, ibinoffset] [, ibinincr] [, iinit]

  Initialization

inoscs -- The number of analysis bins to synthesise. Cannot be larger
than the size of fsrc (see pvsinfo), e.g. as created by pvsanal.
Processing time is directly proportional to inoscs.

ibinoffset (optional, default=0) -- The first (lowest) bin to
resynthesise, counting from 0 (default = 0).

ibinincr (optional) -- Starting from bin ibinoffset, resynthesize bins
ibinincr apart.

iinit (optional) -- Skip reinitialization. This is not currently
implemented for any of these opcodes, and it remains to be seen if it is
even practical.

  Performance

kfmod -- Scale all frequencies by factor kfmod. 1.0 = no change, 2 = up
one octave.

pvsadsyn is experimental, and implements the oscillator bank using a
fast direct calculation method, rather than a lookup table. This takes
advantage of the fact, empirically arrived at, that for the analysis
rates generally used, (and presuming analysis using pvsanal, where
frequencies in a bin change only slightly between frames) it is not
necessary to interpolate frequencies between frames, only amplitudes.
Accurate resynthesis is often contingent on the use of pvsanal with
iwinsize = ifftsize*2.

This opcode is the most likely to change, or be much extended, according
to feedback and advice from users. It is likely that a full
interpolating table-based method will be added, via a further optional
iarg. The parameter list to pvsadsyn mimics that for pvadd, but excludes
spectral extraction.


===========================================================================
pvsanal                                                             *pvsanal*

  Description

Generate an fsig from a mono audio source ain, using phase vocoder
overlap-add analysis.

  Syntax

fsig pvsanal ain, ifftsize, ioverlap, iwinsize, iwintype [, iformat] [, iinit]

  Initialization

ifftsize -- The FFT size in samples. Need not be a power of two (though
these are especially efficient), but must be even. Odd numbers are
rounded up internally. ifftsize determines the number of analysis bins
in fsig, as ifftsize/2 + 1. For example, where ifftsize = 1024, fsig
will contain 513 analysis bins, ordered linearly from the fundamental to
Nyquist. The fundamental of analysis (which in principle gives the
lowest resolvable frequency) is determined as sr/ifftsize. Thus, for the
example just given and assuming sr = 44100, the fundamental of analysis
is 43.07Hz. In practice, due to the phase-preserving nature of the phase
vocoder, the frequency of any bin can deviate bilaterally, so that DC
components are recorded. Given a strongly pitched signal, frequencies in
adjacent bins can bunch very closely together, around partials in the
source, and the lowest bins may even have negative frequencies.

As a rule, the only reason to use a non power-of-two value for ifftsize
would be to match the known fundamental frequency of a strongly pitched
source. Values with many small factors can be almost as efficient as
power-of-two sizes; for example: 384, for a source pitched at around low
A=110Hz.

ioverlap -- The distance in samples (“hop size”) between overlapping
analysis frames. As a rule, this needs to be at least ifftsize/4, e.g.
256 for the example above. ioverlap determines the underlying analysis
rate, as sr/ioverlap. ioverlap does not require to be a simple factor of
ifftsize; for example a value of 160 would be legal. The choice of
ioverlap may be dictated by the degree of pitch modification applied to
the fsig, if any. As a rule of thumb, the more extreme the pitch shift,
the higher the analysis rate needs to be, and hence the smaller the
value for ioverlap. A higher analysis rate can also be advantageous with
broadband transient sounds, such as drums (where a small analysis window
gives less smearing, but more frequency-related errors).

Note that it is possible, and reasonable, to have distinct fsigs in an
orchestra (even in the same instrument), running at different analysis
rates. Interactions between such fsigs is currently unsupported, and the
fsig assignment opcode does not allow copying between fsigs with
different properties, even if the only difference is in ioverlap.
However, this is not a closed issue, as it is possible in theory to
achieve crude rate conversion (especially with regard to in-memory
analysis files) in ways analogous to time-domain techniques.

iwinsize -- The size in samples of the analysis window filter (as set by
iwintype). This must be at least ifftsize, and can usefully be larger.
Though other proportions are permitted, it is recommended that iwinsize
always be an integral multiple of ifftsize, e.g. 2048 for the example
above. Internally, the analysis window (Hamming, von Hann) is multiplied
by a sinc function, so that amplitudes are zero at the boundaries
between frames. The larger analysis window size has been found to be
especially important for oscillator bank resynthesis (e.g. using
pvsadsyn), as it has the effect of increasing the frequency resolution
of the analysis, and hence the accuracy of the resynthesis. As noted
above, iwinsize determines the overall latency of the
analysis/resynthesis system. In many cases, and especially in the
absence of pitch modifications, it will be found that setting
iwinsize=ifftsize works very well, and offers the lowest latency.

iwintype -- The shape of the analysis window. Currently three choices
computed windows implemented:

  * 0 = Hamming window

  * 1 = von Hann window

  * 3 = Kaiser window (not in sliding form)

These are also supported by the PVOC-EX file format. The window type is
stored as an internal attribute of the fsig, together with the other
parameters (see pvsinfo). Other types may be implemented later on; if
the value of wintype is strictly negative then the absolute value is
used as the number of an f-table which must pre-exist. A significant
issue here is the common constraint of f-tables to power-of-two sizes,
so this method does not offer a complete solution. Most users will find
the Hamming window meets all normal needs, and can be regarded as the
default choice.

iformat -- (optional) The analysis format. Currently only one format is
implemented by this opcode:

  * 0 = amplitude + frequency

This is the classic phase vocoder format; easy to process, and a natural
format for oscillator-bank resynthesis. It would be very easy (tempting,
one might say) to treat an fsig frame not purely as a phase vocoder
frame but as a generic additive synthesis frame. It is indeed possible
to use an fsig this way, but it is important to bear in mind that the
two are not, strictly speaking, directly equivalent.

Other important formats (supported by PVOC-EX) are:

  * 1 = amplitude + phase

  * 2 = complex (real + imaginary)

iformat is provided in case it proves useful later to add support for
these other formats. Formats 0 and 1 are very closely related (as the
phase is “wrapped” in both cases - it is a trivial matter to convert
from one to the other), but the complex format might warrant a second
explicit signal type (a “csig”) specifically for convolution-based
processes, and other processes where the full complement of arithmetic
operators may be useful.

iinit -- (optional) Skip reinitialization. This is not currently
implemented for any of these opcodes, and it remains to be seen if it is
even practical.

  Warning

It is unsafe to use the same f-variable for both input and output of pvs
opcodes. Using the same one might lead to undefined behavior on some
opcodes. Use a different one on the left and right sides of the opcode.


===========================================================================
pvsarp                                                               *pvsarp*

  Description

This opcode arpeggiates spectral components, by amplifying one bin and
attenuating all the others around it. Used with an LFO it will provide a
spectral arpeggiator similar to Trevor Wishart's CDP program specarp.

  Syntax

fsig pvsarp fsigin, kbin, kdepth, kgain

  Performance

fsig -- output pv stream

fsigin -- input pv stream

kbin -- target bin, normalised 0 - 1 (0Hz - Nyquist).

kdepth -- depth of attenuation of surrounding bins

kgain -- gain boost applied to target bin

  Warning

It is unsafe to use the same f-variable for both input and output of pvs
opcodes. Using the same one might lead to undefined behavior on some
opcodes. Use a different one on the left and right sides of the opcode.


===========================================================================
pvsbandp                                                           *pvsbandp*

  Description

Filter the pvoc frames, passing bins whose frequency is within a band,
and with linear interpolation for transitional bands.

  Syntax

fsig pvsbandp fsigin, xlowcut, xlowfull, \
      xhighfull, xhighcut[, ktype]

  Performance

fsig -- output pv stream

fsigin -- input pv stream.

xlowcut, xlowfull, xhighfull, xhighcut -- define a trapezium shape for
the band that is passed. The a-rate versions only apply to the sliding
case.

ktype -- specifies the shape of the transitional band. If at the default
value of zero the shape is as below, with linear transition in
amplitude. Other values yield and exponential shape:

(1 - exp( r*type )) / (1 - exp(type))

This includes a linear dB shape when ktype is log(10) or about 2.30.

The opcode performs a band-pass filter with a spectral envelope shaped like

     klowfull __________________________ khighfull
             /                          \
            /                            \
           /                              \
          /                                \
         /                                  \
________/                                    \______________
        klowcut                       khighcut


===========================================================================
pvsbandr                                                           *pvsbandr*

  Description

Filter the pvoc frames, rejecting bins whose frequency is within a band,
and with linear interpolation for transitional bands.

  Syntax

fsig pvsbandr fsigin, xlowcut, xlowfull, \
      xhighfull, xhighcut[, ktype]

  Performance

fsig -- output pv stream

fsigin -- input pv stream.

xlowcut, xlowfull, xhighfull, xhighcut -- define a trapezium shape for
the band that is rejected. The a-rate versions only apply to the sliding
case.

ktype -- specifies the shape of the transitional band. If at the default
value of zero the shape is as below, with linear transition in
amplitude. Other values give an exponential curve

(1 - exp( r*type )) / (1 - exp(type))

This includes a linear dB shape when ktype is log(10) or about 2.30.

The opcode performs a band-reject filter with a spectral envelope shaped
like

        klowcut                       khighcut
________                                      ______________
        \                                    /
         \                                  /
          \                                /
           \                              /  
            \                            /    
     klowfull\__________________________/ khighfull


===========================================================================
pvsbin                                                               *pvsbin*

  Description

Obtain the amp and freq values off a PVS signal bin as k-rate variables.

  Syntax

kamp, kfr pvsbin fsig, kbin

  Performance

kamp -- bin amplitude

kfr -- bin frequency

fsig -- an input pv stream

kbin -- bin number


===========================================================================
pvsblur                                                             *pvsblur*

  Description

Average the amp/freq time functions of each analysis channel for a
specified time (truncated to number of frames). As a side-effect the
input pvoc stream will be delayed by that amount.

  Syntax

fsig pvsblur fsigin, kblurtime, imaxdel

  Performance

fsig -- output pv stream

fsigin -- input pv stream.

kblurtime -- time in secs during which windows will be averaged .

imaxdel -- maximum delay time, used for allocating memory used in the
averaging operation.

This opcode will blur a pvstream by smoothing the amplitude and
frequency time functions (a type of low-pass filtering); the amount of
blur will depend on the length of the averaging period, larger blurtimes
will result in a more pronounced effect.

  Warning

It is unsafe to use the same f-variable for both input and output of pvs
opcodes. Using the same one might lead to undefined behavior on some
opcodes. Use a different one on the left and right sides of the opcode.


===========================================================================
pvsbuffer                                                         *pvsbuffer*

  Description

This opcode sets up and writes to a circular buffer of length ilen
(secs), giving a handle for the buffer and a time pointer, which holds
the current write position (also in seconds). It can be used with one or
more pvsbufread opcodes. Writing is circular, wrapping around at the end
of the buffer.

  Syntax

ihandle, ktime  pvsbuffer fsig, ilen 

  Initialisation

ihandle -- handle identifying this particular buffer, which should be
passed to a reader opcode.

ilen -- buffer length in seconds.

fsig -- an input pv stream

ktime -- the current time of writing in the buffer

pvsbuffer stores fsig in a buffer which can be read by pvsbufread using
the handle ihandle. Different buffers will have different handles so
they can be read independently by different pvsbufread opcodes.
pvsbuffer gives in its output the current time (ktime) inside the ring
buffer which has just been written.


===========================================================================
pvsbufread                                                       *pvsbufread*

  Description

This opcode reads from a circular buffer of length ilen (secs), taking a
handle for the buffer and a time pointer, which holds the current read
position (also in seconds). It is used in conjunction with a pvsbuffer
opocde. Reading is circular, wrapping around at the end of the buffer.

  Syntax

fsig pvsbufread  ktime, khandle[, ilo, ihi, iclear] 

  Initialisation

ilo, ihi -- set the lowest and highest freqs to be read from the buffer
(defaults to 0, Nyquist).

iclear -- set to 1 to clear output fsig before every write (default 1),
0 tells the opcode not to clear the output fsig. This is relevant when
writing to subsets of an fsig frame using ilo, ihi.

  Performance

fsig -- output pv stream

ktime -- time position of reading pointer (in secs).

khandle -- handle identifying the buffer to be read. When using k-rate
handles, it is important to initialise the k-rate variable to a given
existing handle. When changing buffers, fsig buffers need to be
compatible (same fsig format).

With this opcode and pvsbuffer, it is possible to, among other things:

  * time-stretch/compress a fsig stream, by reading it at different rates
  * delay a fsig or portions of it.
  * 'brassage' two or more fsigs by switching buffers, since the reading
    handles are k-rate. Note that, when using k-rate handles, it is
    important to initialise the k-rate variable to a given handle (so
    that the fsig initialisation can take place) and it is only possible
    to switch handles between compatible fsig buffers (with the same
    fftsize and overlap).

  Note

It is important that the handle value passed to pvsbufread is valid and
was created by pvsbuffer. Csound will crash with invalid handles.


===========================================================================
pvsbufread2                                                     *pvsbufread2*

  Description

This opcode reads from a circular buffer of length ilen (secs), taking a
handle for the buffer and a time pointer, which holds the current read
position (also in seconds). It is used in conjunction with a pvsbuffer
opocde. Reading is circular, wrapping around at the end of the buffer.
Extra delay times are taken from a function table, with each point on it
defining a delay time in seconds affecting the corresponding bin.

  Syntax

fsig pvsbufread2  ktime, khandle, ift1, ift2 

  Initialization

ift1 -- function table with at least fftisze/2+1 points where delays (in
secs) for bin amplitudes are set (function table positions are
equivalent to bin numbers)

ift2 -- function table with at least fftisze/2+1 points where delays (in
secs) for bin frequencies are set (function table positions are
equivalent to bin numbers)

  Performance

fsig -- output pv stream

ktime -- time position of reading pointer (in secs).

khandle -- handle identifying the buffer to be read. When using k-rate
handles, it is important to initialise the k-rate variable to a given
existing handle. When changing buffers, fsig buffers need to be
compatible (same fsig format).

With this opcode and pvsbuffer, it is possible to, among other things:

  * time-stretch/compress a fsig stream, by reading it at different rates
  * delay a fsig or portions of it.
  * 'brassage' two or more fsigs by switching buffers, since the reading
    handles are k-rate. Note that, when using k-rate handles, it is
    important to initialise the k-rate variable to a given handle (so
    that the fsig initialisation can take place) and it is only possible
    to switch handles between compatible fsig buffers (with the same
    fftsize and overlap).

  Note

It is important that the handle value passed to pvsbufread2 is valid and
was created by pvsbuffer. Csound will crash with invalid handles.


===========================================================================
pvscale                                                             *pvscale*

  Description

Scale the frequency components of a pv stream, resulting in pitch shift.
Output amplitudes can be optionally modified in order to attempt formant
preservation.

  Syntax

fsig pvscale fsigin, kscal[, kkeepform, kgain, kcoefs]

  Performance

fsig -- output pv stream

fsigin -- input pv stream

kscal -- scaling ratio.

kkeepform -- attempt to keep input signal formants; 0: do not keep
formants; 1: keep formants using a liftered cepstrum method; 2: keep
formants by using a true envelope method (defaults to 0).

kgain -- amplitude scaling (defaults to 1).

kcoefs -- number of cepstrum coefs used in formant preservation
(defaults to 80).

The quality of the pitch shift will be improved with the use of a
Hanning window in the pvoc analysis. Formant preservation method 1 is
less intensive than method 2, which might not be suited to realtime use.

  Warning

It is unsafe to use the same f-variable for both input and output of pvs
opcodes. Using the same one might lead to undefined behavior on some
opcodes. Use a different one on the left and right sides of the opcode.


===========================================================================
pvscent                                                             *pvscent*

  Description

Calculate the spectral centroid of a signal from its discrete Fourier
transform.

  Syntax

kcent pvscent fsig

  Performance

kcent -- the spectral centroid

fsig -- an input pv stream


===========================================================================
pvsceps                                                             *pvsceps*

  Description

  Syntax

keps[] pvsceps fsig[, icoefs]

  Initialization

icoefs -- the number of retained coefficients in the cepstrum output. By
default, no coefficients are liftered.

  Performance

keps[] -- the cepstrum output, an array of size N/2+1, where N is
equivalent to the FFT size of the input fsig.

fsig -- an input pv stream


===========================================================================
pvscross                                                           *pvscross*

  Description

Performs cross-synthesis between two source fsigs.

  Syntax

fsig pvscross fsrc, fdest, kamp1, kamp2

  Performance

The operation of this opcode is identical to that of pvcross (q.v.),
except in using fsigs rather than analysis files, and the absence of
spectral envelope preservation. The amplitudes from fsrc and fdest
(using scale factors kamp1 for fsrc and kamp2 for fdest) are applied to
the frequencies of fsrc. kamp1 and kamp2 must not exceed the range 0 to 1.

With this opcode, cross-synthesis can be performed on real-time audio
input, by using pvsanal to generate fsrc and fdest. These must have the
same format.

  Warning

It is unsafe to use the same f-variable for both input and output of pvs
opcodes. Using the same one might lead to undefined behavior on some
opcodes. Use a different one on the left and right sides of the opcode.


===========================================================================
pvsdemix                                                           *pvsdemix*

  Description

Spectral azimuth-based de-mixing of stereo sources, with a
reverse-panning result. This opcode implements the Azimuth
Discrimination and Resynthesis (ADRess) algorithm, developed by Dan
Barry (Barry et Al. "Sound Source Separation Azimuth Discrimination and
Resynthesis". DAFx'04, Univ. of Napoli). The source separation, or
de-mixing, is controlled by two parameters: an azimuth position (kpos)
and a subspace width (kwidth). The first one is used to locate the
spectral peaks of individual sources on a stereo mix, whereas the second
widens the 'search space', including/exclufing the peaks around kpos.
These two parameters can be used interactively to extract source sounds
from a stereo mix. The algorithm is particularly successful with studio
recordings where individual instruments occupy individual panning
positions; it is, in fact, a reverse-panning algorithm.

  Warning

It is unsafe to use the same f-variable for both input and output of pvs
opcodes. Using the same one might lead to undefined behavior on some
opcodes. Use a different one on the left and right sides of the opcode.

  Syntax

fsig pvsdemix fleft, fright, kpos, kwidth, ipoints

  Performance

fsig -- output pv stream

fleft -- left channel input pv stream.

fright -- right channel pv stream.

kpos -- the azimuth target centre position, which will be de-mixed, from
left to right (-1 <= kpos <= 1). This is the reverse pan-pot control.

kwidth -- the azimuth subspace width, which will determine the number of
points around kpos which will be used in the de-mixing process. (1 <=
kwidth <= ipoints)

ipoints -- total number of discrete points, which will divide each pan
side of the stereo image. This ultimately affects the resolution of the
process.


===========================================================================
pvsdiskin                                                         *pvsdiskin*

  Description

Create an fsig stream by reading a selected channel from a PVOC-EX
analysis file, with frame interpolation.

  Syntax

fsig pvsdiskin SFname,ktscal,kgain[,ioffset, ichan]

  Initialization

Sfname -- Name of the analysis file. This must have the .pvx file
extension.

A multi-channel PVOC-EX file can be generated using the extended pvanal
utility.

ichan -- (optional) The channel to read (counting from 1). Default is 1.

ioff -- start offset from beginning of file (secs) (default: 0) .

  Performance

ktscal -- time scale, ie. the read pointer speed (1 is normal speed,
negative is backwards, 0 < ktscal < 1 is slower and ktscal > 1 is faster)

kgain -- gain scaling.


===========================================================================
pvsdisp                                                             *pvsdisp*

  Description

This opcode will display a PVS signal fsig. Uses X11 or FLTK windows if
enabled, else (or if -g flag is set) displays are approximated in ASCII
characters.

  Syntax

pvsdisp fsig[, ibins, iwtflg] 

  Initialization

iprd -- the period of pvsdisp in seconds.

ibins (optional, default=all bins) -- optionally, display only ibins bins.

iwtflg (optional, default=0) -- wait flag. If non-zero, each pvsdisp is
held until released by the user. The default value is 0 (no wait).

  Performance

pvsdisp -- displays the PVS signal frame-by-frame.


===========================================================================
pvsfilter                                                         *pvsfilter*

  Description

Multiply amplitudes of a pvoc stream by those of a second pvoc stream,
with dynamic scaling.

  Syntax

fsig pvsfilter fsigin, fsigfil, kdepth[, igain]

  Performance

fsig -- output pv stream

fsigin -- input pv stream.

fsigfil -- filtering pvoc stream.

kdepth -- controls the depth of filtering of fsigin by fsigfil .

igain -- amplitude scaling (optional, defaults to 1).

Here the input pvoc stream amplitudes are modified by the filtering
stream, keeping its frequencies intact. As usual, both signals have to
be in the same format.

  Warning

It is unsafe to use the same f-variable for both input and output of pvs
opcodes. Using the same one might lead to undefined behavior on some
opcodes. Use a different one on the left and right sides of the opcode.


===========================================================================
pvsfread                                                           *pvsfread*

  Description

Create an fsig stream by reading a selected channel from a PVOC-EX
analysis file loaded into memory, with frame interpolation. Only format
0 files (amplitude+frequency) are currently supported. The operation of
this opcode mirrors that of pvoc, but outputs an fsig instead of a
resynthesized signal.

  Syntax

fsig pvsfread ktimpt, ifn [, ichan]

  Initialization

ifn -- Name of the analysis file. This must have the .pvx file extension.

A multi-channel PVOC-EX file can be generated using the extended pvanal
utility.

ichan -- (optional) The channel to read (counting from 0). Default is 0.

  Performance

ktimpt -- Time pointer into analysis file, in seconds. See the
description of the same parameter of pvoc for usage.

Note that analysis files can be very large, especially if multi-channel.
Reading such files into memory will very likely incur breaks in the
audio during real-time performance. As the file is read only once, and
is then available to all other interested opcodes, it can be expedient
to arrange for a dedicated instrument to preload all such analysis files
at startup.


===========================================================================
pvsfreeze                                                         *pvsfreeze*

  Description

This opcodes 'freezes' the evolution of pvs stream by locking into
steady amplitude and/or frequency values for each bin. The freezing is
controlled, independently for amplitudes and frequencies, by a
control-rate trigger, which switches the freezing 'on' if equal to or
above 1 and 'off' if below 1.

  Syntax

fsig pvsfreeze fsigin, kfreeza, kfreezf

  Performance

fsig -- output pv stream

fsigin -- input pv stream.

kfreeza -- freezing switch for amplitudes. Freezing is on if above or
equal to 1 and off if below 1.

kfcf -- freezing switch for frequencies. Freezing is on if above or
equal to 1 and off if below 1.

  Warning

It is unsafe to use the same f-variable for both input and output of pvs
opcodes. Using the same one might lead to undefined behavior on some
opcodes. Use a different one on the left and right sides of the opcode.


===========================================================================
pvsftr                                                               *pvsftr*

  Description

Reads amplitude and/or frequency data from function tables.

  Syntax

pvsftr fsrc, ifna [, ifnf]

  Initialization

ifna -- A table, at least inbins in size, that stores amplitude data.
Ignored if ifna = 0

ifnf (optional) -- A table, at least inbins in size, that stores
frequency data. Ignored if ifnf = 0

  Performance

fsrc -- a PVOC-EX formatted source.

Enables the contents of fsrc to be exchanged with function tables for
custom processing. Except when the frame overlap equals ksmps (which
will generally not be the case), the frame data is not updated each
control period. The data in ifna, ifnf should only be processed when
kflag is set to 1. To process only frequency data, set ifna to zero.

As the function tables are required only to store data from fsrc, there
is no advantage in defining then in the score, and they should generally
be created in the instrument, using ftgen.

By exporting amplitude data, say, from one fsig and importing it into
another, basic cross-synthesis (as in pvscross) can be performed, with
the option to modify the data beforehand using the table manipulation
opodes.

Note that the format data in the source fsig is not written to the
tables. This therefore offers a means of transferring amplitude and
frequency data between non-identical fsigs. Used this way, these opcodes
become potentially pathological, and can be relied upon to produce
unexpected results. In such cases, resynthesis using pvsadsyn would
almost certainly be required.

To perform a straight copy from one fsig to another one of identical
format, the conventional assignment syntax can be used:

fsig1 = fsig2

It is not necessary to use function tables in this case.


===========================================================================
pvsftw                                                               *pvsftw*

  Description

Writes amplitude and/or frequency data to function tables.

  Syntax

kflag pvsftw fsrc, ifna [, ifnf]

  Initialization

ifna -- A table, at least inbins in size, that stores amplitude data.
Ignored if ifna = 0

ifnf -- A table, at least inbins in size, that stores frequency data.
Ignored if ifnf = 0

  Performance

kflag -- A flag that has the value of 1 when new data is available, 0
otherwise.

fsrc -- a PVOC-EX formatted source.

Enables the contents of fsrc to be exchanged with function tables, for
custom processing. Except when the frame overlap equals ksmps (which
will generally not be the case), the frame data is not updated each
control period. The data in ifna, ifnf should only be processed when
kflag is set to 1. To process only frequency data, set ifna to zero.

As the functions tables are required only to store data from fsrc, there
is no advantage in defining then in the score. They should generally be
created in the instrument using ftgen.

By exporting amplitude data, say, from one fsig and importing it into
another, basic cross-synthesis (as in pvscross) can be performed, with
the option to modify the data beforehand using the table manipulation
opodes.

Note that the format data in the source fsig is not written to the
tables. This therefore offers a means of transferring amplitude and
frequency data between non-identical fsigs. Used this way, these opcodes
become potentially pathological, and can be relied upon to produce
unexpected results. In such cases, resynthesis using pvsadsyn would
almost certainly be required.

To perform a straight copy from one fsig to another one of identical
format, the conventional assignment syntax can be used:

fsig1 = fsig2

It is not necessary to use function tables in this case.


===========================================================================
pvsfwrite                                                         *pvsfwrite*

  Description

This opcode writes a fsig to a PVOCEX file (which in turn can be read by
pvsfread or other programs that support PVOCEX file input).

  Syntax

pvsfwrite fsig, ifile

  Initialisation

fsig -- fsig input data. ifile -- filename (a string in double-quotes) .


===========================================================================
pvsgain                                                             *pvsgain*

  Description

Scale the amplitude of a pv stream.

  Syntax

fsig pvsgain fsigin, kgain 

  Performance

fsig -- output pv stream

fsigin -- input pv stream

kgain -- amplitude scaling (defaults to 1).

  Warning

It is unsafe to use the same f-variable for both input and output of pvs
opcodes. Using the same one might lead to undefined behavior on some
opcodes. Use a different one on the left and right sides of the opcode.


===========================================================================
pvshift                                                             *pvshift*

  Description

Shift the frequency components of a pv stream, stretching/compressing
its spectrum.

  Syntax

fsig pvshift fsigin, kshift, klowest[, kkeepform, igain, kcoefs]

  Performance

fsig -- output pv stream

fsigin -- input pv stream

kshift -- shift amount (in Hz, positive or negative).

klowest -- lowest frequency to be shifted.

kkeepform -- attempt to keep input signal formants; 0: do not keep
formants; 1: keep formants using a liftered cepstrum method; 2: keep
formants by using a true envelope method (defaults to 0).

kgain -- amplitude scaling (defaults to 1).

kcoefs -- number of cepstrum coefs used in formant preservation
(defaults to 80).

This opcode will shift the components of a pv stream, from a certain
frequency upwards, up or down a fixed amount (in Hz). It can be used to
transform a harmonic spectrum into an inharmonic one. The kkeepform flag
can be used to try and preserve formants for possibly interesting and
unusual spectral modifications.

  Warning

It is unsafe to use the same f-variable for both input and output of pvs
opcodes. Using the same one might lead to undefined behavior on some
opcodes. Use a different one on the left and right sides of the opcode.


===========================================================================
pvsifd                                                               *pvsifd*

  Description

The pvsifd opcode takes an input a-rate signal and performs an
Instantaneous Frequency, magnitude and phase analysis, using the STFT
and pvsifd (Instantaneous Frequency Distribution), as described in
Lazzarini et al, "Time-stretching using the Instantaneous Frequency
Distribution and Partial Tracking", Proc.of ICMC05, Barcelona. It
generates two PV streaming signals, one containing the amplitudes and
frequencies (a similar output to pvsanal) and another containing
amplitudes and unwrapped phases.

  Syntax

ffr,fphs pvsifd ain, ifftsize, ihopsize, iwintype[,iscal]

  Performance

ffr -- output pv stream in AMP_FREQ format

fphs -- output pv stream in AMP_PHASE format

ifftsize -- FFT analysis size, must be power-of-two and integer multiple
of the hopsize.

ihopsize -- hopsize in samples

iwintype -- window type (O: Hamming, 1: Hanning)

iscal -- amplitude scaling (defaults to 1).

  Warning

It is unsafe to use the same f-variable for both input and output of pvs
opcodes. Using the same one might lead to undefined behavior on some
opcodes. Use a different one on the left and right sides of the opcode.


===========================================================================
pvsinfo                                                             *pvsinfo*

  Description

Get format information about fsrc, whether created by an opcode such as
pvsanal, or obtained from a PVOCEX file by pvsfread. This information is
available at init time, and can be used to set parameters for other pvs
opcodes, and in particular for creating function tables (e.g. for
pvsftw), or setting the number of oscillators for pvsadsyn.

  Syntax

ioverlap, inumbins, iwinsize, iformat pvsinfo fsrc

  Initialization

ioverlap -- The stream overlap size.

inumbins -- The number of analysis bins (amplitude+frequency) in fsrc.
The underlying FFT size is calculated as (inumbins -1) * 2.

iwinsize -- The analysis window size. May be larger than the FFT size.

iformat -- The analysis frame format. If fsrc is created by an opcode,
iformat will always be 0, signifying amplitude+frequency. If fsrc is
defined from a PVOC-EX file, iformat may also have the value 1 or 2
(amplitude+phase, complex).


===========================================================================
pvsinit                                                             *pvsinit*

  Description

Performs the equivalent to an init operation on an f-variable.

  Syntax

fsig pvsinit isize[, iolap, iwinsize, iwintype, iformat]

  Performance

fsig -- output pv stream set to zero.

isize -- size of the DFT frame.

iolap -- size of the analysis overlap, defaults to isize/4.

iwinsize -- size of the analysis window, defaults to isize.

iwintype -- type of analysis window, defaults to 1, Hanning.

iformat -- pvsdata format, defaults to 0:PVS_AMP_FREQ.


===========================================================================
pvsin                                                                 *pvsin*

  Description

This opcode retrieves an f-sig from the pvs in software bus, which can
be used to get data from an external source, using the Csound 5 API. A
channel is created if not already existing. The fsig channel is in that
case initialised with the given parameters. It is important to note that
the pvs input and output (pvsout opcode) busses are independent and data
is not shared between them.

  Syntax

fsig pvsin kchan[, isize, iolap, iwinsize, iwintype, iformat]

  Initialization

isize -- initial DFT size,defaults to 1024.

iolap -- size of overlap, defaults to isize/4.

iwinsize -- size of analysis window, defaults to isize.

iwintype -- type of window, defaults to Hanning (1) (see pvsanal)

iformat -- data format, defaults 0 (PVS_AMP_FREQ). Other possible values
are 1 (PVS_AMP_PHASE), 2 (PVS_COMPLEX) or 3 (PVS_TRACKS).

  Performance

fsig -- output fsig.

kchan -- channel number. If non-existent, a channel will be created.


===========================================================================
pvslock                                                             *pvslock*

  Description

This opcode searches for spectral peaks and then locks the frequencies
around those peaks. This is similar to phase-locking in non-streaming PV
processing. It can be used to improve timestretching and pitch-shifting
quality in PV processing.

  Syntax

fsig pvslock fsigin, klock

  Performance

fsig -- output pv stream

fsigin -- input pv stream.

klock -- frequency lock, 1 -> lock, 0 -> unlock (bypass).

  Warning

It is unsafe to use the same f-variable for both input and output of pvs
opcodes. Using the same one might lead to undefined behavior on some
opcodes. Use a different one on the left and right sides of the opcode.


===========================================================================
pvsmaska                                                           *pvsmaska*

  Description

Modify amplitudes of fsrc using function table, with dynamic scaling.

  Syntax

fsig pvsmaska fsrc, ifn, kdepth

  Initialization

ifn -- The f-table to use. Given fsrc has N analysis bins, table ifn
must be of size N or larger. The table need not be normalized, but
values should lie within the range 0 to 1. It can be supplied from the
score in the usual way, or from within the orchestra by using pvsinfo to
find the size of fsrc, (returned by pvsinfo in inbins), which can then
be passed to ftgen to create the f-table.

  Performance

kdepth -- Controls the degree of modification applied to fsrc, using
simple linear scaling. 0 leaves amplitudes unchanged, 1 applies the full
profile of ifn.

Note that power-of-two FFT sizes are particularly convenient when using
table-based processing, as the number of analysis bins (inbins) is then
a power-of-two plus one, for which an exactly matching f-table can be
created. In this case it is important that the f-table be created with a
size of inbins, rather than as a power of two, as the latter will copy
the first table value to the guard point, which is inappropriate for
this opcode.

  Warning

It is unsafe to use the same f-variable for both input and output of pvs
opcodes. Using the same one might lead to undefined behavior on some
opcodes. Use a different one on the left and right sides of the opcode.


===========================================================================
pvsmix                                                               *pvsmix*

  Description

Mix 'seamlessly' two pv signals. This opcode combines the most prominent
components of two pvoc streams into a single mixed stream.

  Syntax

fsig pvsmix fsigin1, fsigin2

  Performance

fsig -- output pv stream

fsigin1 -- input pv stream.

fsigin2 -- input pv stream, which must have same format as fsigin1.

  Warning

It is unsafe to use the same f-variable for both input and output of pvs
opcodes. Using the same one might lead to undefined behavior on some
opcodes. Use a different one on the left and right sides of the opcode.


===========================================================================
pvsmorph                                                           *pvsmorph*

  Description

Performs morphing (or interpolation) between two source fsigs.

  Syntax

fsig pvsmorph fsig1, fsig2, kampint, kfrqint

  Performance

The operation of this opcode is similar to that of pvinterp (q.v.),
except in using fsigs rather than analysis files, and the absence of
spectral envelope preservation. The amplitudes and frequencies of fsig1
are interpolated with those of fsig2, depending on the values of kampint
and kfrqint, respectively. These range between 0 and 1, where 0 means
fsig1 and 1, fsig2. Anything in between will interpolate amps and/or
freqs of the two fsigs.

With this opcode, morphing can be performed on real-time audio input, by
using pvsanal to generate fsig1 and fsig2. These must have the same format.

  Warning

It is unsafe to use the same f-variable for both input and output of pvs
opcodes. Using the same one might lead to undefined behavior on some
opcodes. Use a different one on the left and right sides of the opcode.


===========================================================================
pvsmooth                                                           *pvsmooth*

  Description

Smooth the amplitude and frequency time functions of a pv stream using a
1st order lowpass IIR with time-varying cutoff frequency. This opcode
uses the same filter as the tone opcode, but this time acting separately
on the amplitude and frequency time functions that make up a pv stream.
The cutoff frequency parameter runs at the control-rate, but unlike tone
and tonek, it is not specified in Hz, but as fractions of 1/2 frame-rate
(actually the pv stream sampling rate), which is easier to understand.
This means that the highest cutoff frequency is 1 and the lowest 0; the
lower the frequency the smoother the functions and more pronounced the
effect will be.

These are filters applied to control signals so the effect is basically
blurring the spectral evolution. The effects produced are more or less
similar to pvsblur, but with two important differences: 1.smoothing of
amplitudes and frequencies use separate sets of filters; and 2. there is
no increase in computational cost when higher amounts of 'blurring'
(smoothing) are desired.

  Syntax

fsig pvsmooth fsigin, kacf, kfcf

  Performance

fsig -- output pv stream

fsigin -- input pv stream.

kacf -- amount of cutoff frequency for amplitude function filtering,
between 0 and 1, in fractions of 1/2 frame-rate.

kfcf -- amount of cutoff frequency for frequency function filtering,
between 0 and 1, in fractions of 1/2 frame-rate.

  Warning

It is unsafe to use the same f-variable for both input and output of pvs
opcodes. Using the same one might lead to undefined behavior on some
opcodes. Use a different one on the left and right sides of the opcode.


===========================================================================
pvsout                                                               *pvsout*

  Description

This opcode writes a fsig to a channel of the pvs output bus. Note that
the pvs out bus and the pvs in bus are separate and independent. A new
channel is created if non-existent.

  Syntax

pvsout fsig, kchan

  Performance

fsig -- fsig input data.

kchan -- pvs out bus channel number.


===========================================================================
pvsosc                                                               *pvsosc*

  Description

Generates periodic signal spectra in AMP-FREQ format, with the option of
four wave types:

 1. sawtooth-like (harmonic weight 1/n, where n is partial number)
 2. square-like (similar to 1., but only odd partials)
 3. pulse (all harmonics with same weight)
 4. cosine

Complex waveforms (ie. all types except cosine) contain all harmonics up
to the Nyquist. This makes pvsosc an option for generation of
band-limited periodic waves. In addition, types can be changed using a
k-rate variable.

  Syntax

fsig pvsosc kamp, kfreq, ktype, isize [,ioverlap] [, iwinsize] [, iwintype] [, iformat]

  Initialisation

fsig -- output pv stream set to zero.

isize -- size of analysis frame and window.

ioverlap -- (Optional) size of overlap, defaults to isize/4.

iwinsize -- (Optional) window size, defaults to isize.

iwintype -- (Optional) window type, defaults to Hanning. The choices are
currently:

  * 0 = Hamming window

  * 1 = von Hann window

iformat -- (Optional) data format, defaults to 0 which produces AMP:FREQ
data. That is currently the only option.

  Performance

kamp -- signal amplitude. Note that the actual signal amplitude can,
depending on wave type and frequency, vary slightly above or below this
value. Generally the amplitude will tend to exceed kamp on higher
frequencies (> 1000 Hz) and be reduced on lower ones. Also due to the
overlap-add process, when resynthesing with pvsynth, frequency glides
will cause the output amplitude to fluctuate above and below kamp.

kfreq -- fundamental frequency in Hz.

ktype -- wave type: 1. sawtooh-like, 2.square-like, 3.pulse and any
other value for cosine.


===========================================================================
pvspitch                                                           *pvspitch*

  Description

Track the pitch and amplitude of a PVS signal as k-rate variables.

  Syntax

kfr, kamp pvspitch fsig, kthresh

  Performance

kamp -- Amplitude of fundamental frequency

kfr -- Fundamental frequency

fsig -- an input pv stream

kthresh -- analysis threshold (between 0 and 1). Higher values will
eliminate low-amplitude components from the analysis.

  Performance

The pitch detection algorithm implemented by pvspitch is based upon J.
F. Schouten's hypothesis of the neural processes of the brain used to
determine the pitch of a sound after the frequency analysis of the
basilar membrane. Except for some further considerations, pvspitch
essentially seeks out the highest common factor of an incoming sound's
spectral peaks to find the pitch that may be attributed to it.

In general, input sounds that exhibit pitch will also exhibit peaks in
their spectrum according to where their harmonics lie. There are some
the exceptions, however. Some sounds whose spectral representation is
continuous can impart a sensation of pitch. Such sounds are explained by
the centroid or center of gravity of the spectrum and are beyond the
scope of the method of pitch detection implemented by pvspitch (Using
opcodes like pvscent might be more appriopriate in these cases).

pvspitch is able (using a previous analysis fsig generated by pvsanal)
to locate the spectral peaks of a signal. The threshold parameter
(kthresh) is of utmost importance, as adjusting it can introduce weak
yet significant harmonics into the calculation of the fundamental.
However, bringing kthresh too low would allow harmonically unrelated
partials into the analysis algorithm and this will compromise the
method's accuracy. These initial steps emulate the response of the
basilar membrane by identifying physical characteristics of the input
sound. The choice of kthresh depends on the actual level of the input
signal, since its range (from 0 to 1) spans the whole dynamic range of
an analysis bin (from -inf to 0dBFS).

It is important to remember that the input to the pvspitch opcode is
assumed to be characterised by strong partials within its spectrum. If
this is not the case, the results outputted by the opcode may not bear
any relation to the pitch of the input signal. If a spectral frame with
many unrelated partials was analysed, the greatest common factor of
these frequency values that allows for adjacent “harmonics” would be
chosen. Thus, noisy frames can be characterised by low frequency outputs
of pvspitch. This fact allows for a primitive type of instrumental
transient detection, as the attack portion of some instrumental tones
contain inharmonic components. Should the lowest frequency of the
analysed melody be known, then all frequencies detected below this
threshold are inaccurate readings, due to the presence of unrelated
partials.

In order to facilitate efficient testing of the pvspitch algorithm, an
amplitude value proportional to the one in the observed in the signal
frame is also outputted (kamp). The results of pvspitch can then be
employed to drive an oscillator whose pitch can be audibly compared with
that of the original signal (In the example below, an oscillator
generates a signal which appears a fifth above the detected pitch).


===========================================================================
pvstanal                                                           *pvstanal*

  Description

pvstanal implements phase vocoder analysis by reading function tables
containing sampled-sound sources, with GEN01, and pvstanal will accept
deferred allocation tables.

This opcode allows for time and frequency-independent scaling. Time is
advanced internally, but controlled by a tempo scaling parameter; when
an onset is detected, timescaling is momentarily stopped to avoid
smearing of attacks. The quality of the effect is generally improved
with phase locking switched on.

pvstanal will also scale pitch, independently of frequency, using a
transposition factor (k-rate).

  Syntax

fsig pvstanal ktimescal, kamp, kpitch, ktab, [kdetect, kwrap, ioffset,ifftsize, ihop, idbthresh]

  Initialization

ifftsize -- FFT size (power-of-two), defaults to 2048.

ihop -- hopsize, defaults to 512

ioffset -- startup read offset into table, in secs.

idbthresh -- threshold for onset detection, based on dB power spectrum
ratio between two successive windows. A detected ratio above it will
cancel timescaling momentarily, to avoid smearing (defaults to 1). By
default anything more than a 1 dB inter-frame power difference will be
detected as an onset.

  Performance

ktimescal -- timescaling ratio, < 1 stretch, > 1 contract.

kamp -- amplitude scaling

kpitch -- grain pitch scaling (1=normal pitch, < 1 lower, > 1 higher;
negative, backwards)

kdetect -- 0 or 1, to switch onset detection/processing. The onset
detector checks for power difference between analysis windows. If more
than what has been specified in the dbthresh parameter, an onset is
declared. It suspends timescaling momentarily so the onsets are not
modified.

ktab -- source signal function table. Deferred-allocation tables (see
GEN01) are accepted, but the opcode expects a mono source. Tables can be
switched at k-rate.

kwrap -- 0 or 1, to switch on/off table wrap-around read (default to 1)


===========================================================================
pvstencil                                                         *pvstencil*

  Description

Transforms a pvoc stream according to a masking function table; if the
pvoc stream amplitude falls below the value of the function for a
specific pvoc channel, it applies a gain to that channel.

The pvoc stream amplitudes are compared to a masking table, if the fall
below the table values, they are scaled by kgain. Prior to the
operation, table values are scaled by klevel, which can be used as
masking depth control.

Tables have to be at least fftsize/2 in size; for most GENS it is
important to use an extended-guard point (size power-of-two plus one),
however this is not necessary with GEN43.

One of the typical uses of pvstencil would be in noise reduction. A
noise print can be analysed with pvanal into a PVOC-EX file and loaded
in a table with GEN43. This then can be used as the masking table for
pvstencil and the amount of reduction would be controlled by kgain.
Skipping post-normalisation will keep the original noise print average
amplitudes. This would provide a good starting point for a successful
noise reduction (so that klevel can be generally set to close to 1).

Other possible transformation effects are possible, such as filtering
and `inverse-masking'.

  Syntax

fsig pvstencil fsigin, kgain, klevel, iftable

  Performance

fsig -- output pv stream

fsigin -- input pv stream.

kgain -- `stencil' gain.

klevel -- masking function level (scales the ftable prior to
`stenciling') .

iftable -- masking function table.

  Warning

It is unsafe to use the same f-variable for both input and output of pvs
opcodes. Using the same one might lead to undefined behavior on some
opcodes. Use a different one on the left and right sides of the opcode.


===========================================================================
pvsvoc                                                               *pvsvoc*

  Description

This opcode provides support for cross-synthesis of amplitudes and
frequencies. It takes the amplitudes of one input fsig and combines with
frequencies from another. It is a spectral version of the well-known
channel vocoder.

  Syntax

fsig pvsvoc famp, fexc, kdepth, kgain [,kcoefs]

  Performance

fsig -- output pv stream

famp -- input pv stream from which the amplitudes will be extracted

fexc -- input pv stream from which the frequencies will be taken

kdepth -- depth of effect, affecting how much of the frequencies will be
taken from the second fsig: 0, the output is the famp signal, 1 the
output is the famp amplitudes and fexc frequencies.

kgain -- gain boost/attenuation applied to the output.

kcoefs -- number of cepstrum coefs used in spectral envelope estimation
(defaults to 80).

  Warning

It is unsafe to use the same f-variable for both input and output of pvs
opcodes. Using the same one might lead to undefined behavior on some
opcodes. Use a different one on the left and right sides of the opcode.


===========================================================================
pvsynth                                                             *pvsynth*

  Description

Resynthesise phase vocoder data (f-signal) using a FFT overlap-add.

  Syntax

ares pvsynth fsrc, [iinit]

  Performance

ares -- output audio signal

fsrc -- input signal

iinit -- not yet implemented.


===========================================================================
pvswarp                                                             *pvswarp*

  Description

Warp the spectral envelope of a PVS signal by means of shifting and
scaling.

  Syntax

fsig pvswarp fsigin, kscal, kshift[, klowest, kmeth, kgain, kcoefs]

  Performance

fsig -- output pv stream

fsigin -- input pv stream

kscal -- spectral envelope scaling ratio. Values > 1 stretch the
envelope and < 1 compress it.

kshift -- spectral envelope shift, values > 0 shift the envelope
linearly upwards and values < 0 shift it downwards.

klowest -- lowest frequency shifted (affects only kshift, defaults to 0).

kmethod -- spectral envelope extraction method 1: liftered cepstrum
method; 2: true envelope method (defaults to 1).

kgain -- amplitude scaling (defaults to 1).

kcoefs -- number of cepstrum coefs used in formant preservation
(defaults to 80).

  Warning

It is unsafe to use the same f-variable for both input and output of pvs
opcodes. Using the same one might lead to undefined behavior on some
opcodes. Use a different one on the left and right sides of the opcode.


===========================================================================
pvs2tab                                                             *pvs2tab*

  Description

Copies a pvs frame to a t-variable. Currently only AMP+FREQ and
AMP+PHASE formats allowed. Since t-vars are an earlier version of k-rate
arrays, the opcode also works with these. The opcode pvs2array is an
alias of this one.

  Syntax

kframe pvs2tab tvar|kvar[], fsig

  Performance

kframe -- current copied frame number. It can be used to detect when a
new frame has been copied.

tvar|kvar[] -- t-variable or k-rate array containing the output. It is
produced at every k-period, but may not contain a new frame, pvs frames
are produced at their own frame rate that is independent of kr.
Generally, this vector needs to be big enough to contain the frame
samples, i.e. N+2 (N is the dft size). If smaller, only a portion of the
frame will be copied; if bigger, unused points will exist at higher
indexes.

fsig -- input fsig to be copied.


===========================================================================
pyassign Opcodes                                                   *pyassign*

  Syntax

pyassign "variable", kvalue

pyassigni "variable", ivalue

pylassign "variable", kvalue

pylassigni "variable", ivalue

pyassignt ktrigger, "variable", kvalue

pylassignt ktrigger, "variable", kvalue

  Description

Assign the value of the given Csound variable to a Python variable
possibly destroying its previous content. The resulting Python object
will be a float.


===========================================================================
pycall Opcodes                                                       *pycall*

  Syntax

                                        pycall   "callable", karg1, ...

kresult                                 pycall1  "callable", karg1, ...

kresult1, kresult2                      pycall2  "callable", karg1, ...

kr1, kr2, kr3                           pycall3  "callable", karg1, ...

kr1, kr2, kr3, kr4                      pycall4  "callable", karg1, ...

kr1, kr2, kr3, kr4, kr5                 pycall5  "callable", karg1, ...

kr1, kr2, kr3, kr4, kr5, kr6            pycall6  "callable", karg1, ...

kr1, kr2, kr3, kr4, kr5, kr6, kr7       pycall7  "callable", karg1, ...

kr1, kr2, kr3, kr4, kr5, kr6, kr7, kr8  pycall8  "callable", karg1, ...

                                        pycallt   ktrigger, "callable", karg1, ...

kresult                                 pycall1t  ktrigger, "callable", karg1, ...

kresult1, kresult2                      pycall2t  ktrigger, "callable", karg1, ...

kr1, kr2, kr3                           pycall3t  ktrigger, "callable", karg1, ...

kr1, kr2, kr3, kr4                      pycall4t  ktrigger, "callable", karg1, ...

kr1, kr2, kr3, kr4, kr5                 pycall5t  ktrigger, "callable", karg1, ...

kr1, kr2, kr3, kr4, kr5, kr6            pycall6t  ktrigger, "callable", karg1, ...

kr1, kr2, kr3, kr4, kr5, kr6, kr7       pycall7t  ktrigger, "callable", karg1, ...

kr1, kr2, kr3, kr4, kr5, kr6, kr7, kr8  pycall8t  ktrigger, "callable", karg1, ...

                                        pycalli   "callable", karg1, ...

iresult                                 pycall1i  "callable", iarg1, ...

iresult1, iresult2                      pycall2i  "callable", iarg1, ...

ir1, ir2, ir3                           pycall3i  "callable", iarg1, ...

ir1, ir2, ir3, ir4                      pycall4i  "callable", iarg1, ...

ir1, ir2, ir3, ir4, ir5                 pycall5i  "callable", iarg1, ...

ir1, ir2, ir3, ir4, ir5, ir6            pycall6i  "callable", iarg1, ...

ir1, ir2, ir3, ir4, ir5, ir6, ir7       pycall7i  "callable", iarg1, ...

ir1, ir2, ir3, ir4, ir5, ir6, ir7, ir8  pycall8i  "callable", iarg1, ...

pycalln   "callable", nresults, kresult1, ..., kresultn, karg1, ...

pycallni  "callable", nresults, iresult1, ..., iresultn, iarg1,  ...

                                        pylcall   "callable", karg1, ...

kresult                                 pylcall1  "callable", karg1, ...

kresult1, kresult2                      pylcall2  "callable", karg1, ...

kr1, kr2, kr3                           pylcall3  "callable", karg1, ...

kr1, kr2, kr3, kr4                      pylcall4  "callable", karg1, ...

kr1, kr2, kr3, kr4, kr5                 pylcall5  "callable", karg1, ...

kr1, kr2, kr3, kr4, kr5, kr6            pylcall6  "callable", karg1, ...

kr1, kr2, kr3, kr4, kr5, kr6, kr7       pylcall7  "callable", karg1, ...

kr1, kr2, kr3, kr4, kr5, kr6, kr7, kr8  pylcall8   "callable", karg1, ...

                                        pylcallt   ktrigger, "callable", karg1, ...

kresult                                 pylcall1t  ktrigger, "callable", karg1, ...

kresult1, kresult2                      pylcall2t  ktrigger, "callable", karg1, ...

kr1, kr2, kr3                           pylcall3t  ktrigger, "callable", karg1, ...

kr1, kr2, kr3, kr4                      pylcall4t  ktrigger, "callable", karg1, ...

kr1, kr2, kr3, kr4, kr5                 pylcall5t  ktrigger, "callable", karg1, ...

kr1, kr2, kr3, kr4, kr5, kr6            pylcall6t  ktrigger, "callable", karg1, ...

kr1, kr2, kr3, kr4, kr5, kr6, kr7       pylcall7t  ktrigger, "callable", karg1, ...

kr1, kr2, kr3, kr4, kr5, kr6, kr7, kr8  pylcall8t  ktrigger, "callable", karg1, ...

                                        pylcalli   "callable", karg1, ...

iresult                                 pylcall1i  "callable", iarg1, ...

iresult1, iresult2                      pylcall2i  "callable", iarg1, ...

ir1, ir2, ir3                           pylcall3i  "callable", iarg1, ...

ir1, ir2, ir3, ir4                      pylcall4i  "callable", iarg1, ...

ir1, ir2, ir3, ir4, ir5                 pylcall5i  "callable", iarg1, ...

ir1, ir2, ir3, ir4, ir5, ir6            pylcall6i  "callable", iarg1, ...

ir1, ir2, ir3, ir4, ir5, ir6, ir7       pylcall7i  "callable", iarg1, ...

ir1, ir2, ir3, ir4, ir5, ir6, ir7, ir8  pylcall8i  "callable", iarg1, ...

pylcalln   "callable", nresults, kresult1, ..., kresultn, karg1, ...

pylcallni  "callable", nresults, iresult1, ..., iresultn, iarg1, ...

  Description

This family of opcodes call the specified Python callable at k-time and
i-time (i suffix), passing the given arguments. The call is perfomed in
the global environment and the result (the returning value) is copied
into the Csound output variables specified.

They pass any number of parameters which are cast to float inside the
Python interpreter.

The pycall/pycalli, pycall1/pycall1i ... pycall8/pycall8i opcodes can
accomodate for a number of results ranging from 0 to 8 according to
their numerical prefix (0 is omitted).

The pycalln/pycallni opcodes can accomodate for any number of results:
the callable name is followed by the number of output arguments, then
come the list of Csound output variable and the list of parameters to be
passed.

The returning value of the callable must be |None| for pycall or
pycalli, a float for pycall1i or pycall1i and a tuple (with proper size)
of floats for the pycall2/pycall2i ... pycall8/pycall8i and
pycalln/pycallni opcodes.


===========================================================================
pyeval Opcodes                                                       *pyeval*

  Syntax

kresult pyeval "expression"

iresult pyevali "expression"

kresult pyleval "expression"

iresult pylevali "expression"

kresult pyevalt ktrigger, "expression"

kresult pylevalt ktrigger, "expression"

  Description

These opcodes evaluate a generic Python expression and store the result
in a Csound variable at k-time or i-time (i suffix).

The expression must evaluate in a float or an object that can be cast to
a float.

They can be used effectively to trasfer data from a Python object into a
Csound variable.


===========================================================================
pyexec Opcodes                                                       *pyexec*

  Syntax

pyexec "filename"

pyexeci "filename"

pylexec "filename"

pylexeci "filename"

pyexect ktrigger, "filename"

plyexect ktrigger, "filename"

  Description

Execute a script from a file at k-time or i-time (i suffix).

This is not the same as calling the script with the |system()| call,
since the code is executed by the embedded interpreter.

The code contained in the specified file is executed in the global
environment for opcodes pyexec and pyexeci and in the private
environment for the opcodes pylexec and pylexeci.

These opcodes perform no message passing. However, since the statement
has access to the main namespace and the private namespace, it can
interact with objects previously created in that environment.

The "local" version of the pyexec opcodes are useful when the code ran
by different instances of an instrument should not interact.


===========================================================================
pyinit Opcodes                                                       *pyinit*

  Syntax

pyinit

  Description

In Csound, you must first invoke the pyinit opcode in the orchestra
header to initialize the Python interpreter, before using any of the
other Python opcodes.

But if you use the Python opcodes within CsoundAC, or from a python
frontend using the csnd6 module, Csound, you need not invoke pyinit,
because the Python interpreter will have already been initialized. In
this case, CsoundAC (or the csnd6 python module) automatically creates a
Python interface to the Csound API. In CsoundAC, this exists in the form
a global instance of the |CsoundAC.CppSound| class named |csound|. From
a python frontend which imports the csnd6 module, the name of the
variable holding the Csound instance will depend on the frontend code.
Therefore, Python code written in the Csound orchestra has access to the
global |csound| object.

The running Csound instance in which pyinit has been called is stored in
a global python variable called _CSOUND_. This holds the actual memory
address of the instance and it can be used with the csnd6 module via the
csoundGetInstance(instance) call. This python function returns an object
that can be used with all the Csound API functions.


===========================================================================
pyrun Opcodes                                                         *pyrun*

  Syntax

pyrun "statement"

pyruni "statement"

pylrun "statement"

pylruni "statement"

pyrunt ktrigger, "statement"

pylrunt ktrigger, "statement"

  Description

Execute the specified Python statement at k-time (pyrun and pylrun) or
i-time (pyruni and pylruni).

The statement is executed in the global environment for pyrun and pyruni
or the local environment for pylrun and pylruni.

These opcodes perform no message passing. However, since the statement
have access to the main namespace and the private namespace, it can
interact with objects previously created in that environment.

The "local" version of the pyrun opcodes are useful when the code ran by
different instances of an instrument should not interact.


===========================================================================
pwd                                                                     *pwd*

  Description

pwd call the operating system to determine the current directory
(folder). pwd runs at i-time only.

  Syntax

Sres pwd

  Performance

Sres -- the returned string.


===========================================================================
qinf                                                                   *qinf*

  Description

Returns the number of times the argument is not a number, with the sign
of the first infinity.

  Syntax

qinf(x) (no rate restriction)


===========================================================================
qnan                                                                   *qnan*

  Description

Returns the number of times the argument is not a number.

  Syntax

qnan(x) (no rate restriction)


===========================================================================
r2c                                                                     *r2c*

  Description

Converts a real-valued input array in real-imaginary interleaved complex
format, setting its imaginary parts to 0. The output array will be
double the size of the input. This is a utility operation to facilitate
complex-value operations on real arrays.

  Syntax

kout[] r2c kin[]

  Performance

kout[] -- output array containing the complex-valued real-imaginary
output. It will be created if it does not exist.

kin[] -- input array containing the real-valued input.


===========================================================================
rand                                                                   *rand*

  Description

Output is a controlled random number series between -amp and +amp

  Syntax

ares rand xamp [, iseed] [, isel] [, ioffset]

kres rand xamp [, iseed] [, isel] [, ioffset]

  Initialization

iseed (optional, default=0.5) -- a seed value for the recursive
pseudo-random formula. A value between 0 and 1 will produce an initial
output of kamp * iseed. A value greater than 1 will be seeded from the
system clock. A negative value will cause seed re-initialization to be
skipped. The default seed value is .5.

isel (optional, default=0) -- if zero, a 16-bit number is generated. If
non-zero, a 31-bit random number is generated. Default is 0.

ioffset (optional, default=0) -- a base value added to the random
result. New in Csound version 4.03.

  Performance

kamp, xamp -- range over which random numbers are distributed.

ares, kres -- Random number produced.

The internal pseudo-random formula produces values which are uniformly
distributed over the range kamp to -kamp. rand will thus generate
uniform white noise with an R.M.S value of kamp / root 2.

The value ares or kres is within is a half-closed interval which
contains -xamp, but never contains +xamp.


===========================================================================
randh                                                                 *randh*

  Description

Generates random numbers and holds them for a period of time.

  Syntax

ares randh xamp, xcps [, iseed] [, isize] [, ioffset]

kres randh kamp, kcps [, iseed] [, isize] [, ioffset]

  Initialization

iseed (optional, default=0.5) -- seed value for the recursive
pseudo-random formula. A value between 0 and +1 will produce an initial
output of kamp * iseed. A negative value will cause seed
re-initialization to be skipped. A value greater than 1 will seed from
system time, this is the best option to generate a different random
sequence for each run.

isize (optional, default=0) -- if zero, a 16 bit number is generated. If
non-zero, a 31-bit random number is generated. Default is 0.

ioffset (optional, default=0) -- a base value added to the random
result. New in Csound version 4.03.

  Performance

kamp, xamp -- range over which random numbers are distributed.

kcps, xcps -- the frequency which new random numbers are generated.

The internal pseudo-random formula produces values which are uniformly
distributed over the range -kamp to +kamp. rand will thus generate
uniform white noise with an R.M.S value of kamp / root 2.

The remaining units produce band-limited noise: the kcps and xcps
parameters permit the user to specify that new random numbers are to be
generated at a rate less than the sampling or control frequencies. randh
will hold each new number for the period of the specified cycle.


===========================================================================
randi                                                                 *randi*

  Description

Generates a controlled random number series with interpolation between
each new number.

  Syntax

ares randi xamp, xcps [, iseed] [, isize] [, ioffset]

kres randi kamp, kcps [, iseed] [, isize] [, ioffset]

  Initialization

iseed (optional, default=0.5) -- seed value for the recursive
pseudo-random formula. A value between 0 and +1 will produce an initial
output of kamp * iseed. A negative value will cause seed
re-initialization to be skipped. A value greater than 1 will seed from
system time, this is the best option to generate a different random
sequence for each run.

isize (optional, default=0) -- if zero, a 16 bit number is generated. If
non-zero, a 31-bit random number is generated. Default is 0.

ioffset (optional, default=0) -- a base value added to the random
result. New in Csound version 4.03.

  Performance

kamp, xamp -- range over which random numbers are distributed.

kcps, xcps -- the frequency which new random numbers are generated.

The internal pseudo-random formula produces values which are uniformly
distributed over the range kamp to -kamp. rand will thus generate
uniform white noise with an R.M.S value of kamp / root 2.

The remaining units produce band-limited noise: the kcps and xcps
parameters permit the user to specify that new random numbers are to be
generated at a rate less than the sampling or control frequencies. randi
will produce straight-line interpolation between each new number and the
next.


===========================================================================
random                                                               *random*

  Description

Generates is a controlled pseudo-random number series between min and
max values.

  Syntax

ares random kmin, kmax

ires random imin, imax

kres random kmin, kmax

  Initialization

imin -- minimum range limit

imax -- maximum range limit

  Performance

kmin -- minimum range limit

kmax -- maximum range limit

The random opcode is similar to linrand and trirand but sometimes I
[Gabriel Maldonado] find it more convenient because allows the user to
set arbitrary minimum and maximum values.


===========================================================================
randomh                                                             *randomh*

  Description

Generates random numbers with a user-defined limit and holds them for a
period of time.

  Syntax

ares randomh kmin, kmax, xcps [,imode] [,ifirstval]

kres randomh kmin, kmax, kcps [,imode] [,ifirstval]

  Initialization

imode (optional, default=0) -- generation mode of the first output value
(see below)

ifirstval (optional, default=0) -- first output value

  Performance

kmin -- minimum range limit

kmax -- maximum range limit

kcps, xcps -- rate of random break-point generation

The randomh opcode is similar to randh but allows the user to set
arbitrary minimum and maximum values.

When imode = 0 (the default), the kmin argument value is outputted
during 1/kcps (resp. 1/xcps) seconds at the beginning of the note. Then,
the normal process takes place with a new random number generated and
held every 1/kcps (resp. 1/xcps) seconds.

When imode = 2, the ifirstval argument value is outputted during 1/kcps
(resp. 1/xcps) seconds at the beginning of the note. Then, the normal
process takes place with a new random number generated and held every
1/kcps (resp. 1/xcps) seconds.

When imode = 3, the generation process begins with a random value from
the initialization time.


===========================================================================
randomi                                                             *randomi*

  Description

Generates a user-controlled random number series with interpolation
between each new number.

  Syntax

ares randomi kmin, kmax, xcps [,imode] [,ifirstval]

kres randomi kmin, kmax, kcps [,imode] [,ifirstval]

  Initialization

imode (optional, default=0) -- first interpolation cycle mode (see below)

ifirstval (optional, default=0) -- first output value

  Performance

kmin -- minimum range limit

kmax -- maximum range limit

kcps, xcps -- rate of random break-point generation

The randomi opcode is similar to randi but allows the user to set
arbitrary minimum and maximum values.

When imode = 0 (the default), the kmin argument value is outputted
during 1/kcps (resp. 1/xcps) seconds at the beginning of the note,
before the first random number is generated. Then the normal
interpolation process takes place, first between kmin and the first
random number generated, and then between successive generated random
numbers, each interpolation cycle having a duration of 1/kcps (resp.
1/xcps) seconds.

When imode = 1, a random number is generated at initialization and
interpolation begins immediately between the kmin argument value and
that random number.

When imode = 2, a random number is generated at initialization and
interpolation begins immediately between the ifirstval argument value
and that random number.

When imode = 3, two random numbers are generated at initialization as
breakpoints for the first interpolation cycle.


===========================================================================
rbjeq                                                                 *rbjeq*

  Description

Parametric equalizer and filter opcode with 7 filter types, based on
algorithm by Robert Bristow-Johnson.

  Syntax

ar rbjeq asig, kfco, klvl, kQ, kS[, imode]

  Initialization

imode ( optional, defaults to zero) - sum of:

  * 1: skip initialization (should be used in tied, or re-initialized
    notes only)

and exactly one of the following values to select filter type:

  * 0: resonant lowpass filter. kQ controls the resonance: at the cutoff
    frequency (kfco), the amplitude gain is kQ (e.g. 20 dB for kQ = 10),
    and higher kQ values result in a narrower resonance peak. If kQ is
    set to sqrt(0.5) (about 0.7071), there is no resonance, and the
    filter has a response that is very similar to that of butterlp. If
    kQ is less than sqrt(0.5), there is no resonance, and the filter has
    a -6 dB / octave response from about kfco * kQ to kfco. Above kfco,
    there is always a -12 dB / octave cutoff.

The rbjeq lowpass filter is basically the same as ar pareq asig,
    kfco, 0, kQ, 2 but is faster to calculate.

  * 2: resonant highpass filter. The parameters are the same as for the
    lowpass filter, but the equivalent filter is butterhp if kQ is
    0.7071, and "ar pareq asig, kfco, 0, kQ, 1" in other cases.

  * 4: bandpass filter. kQ controls the bandwidth, which is kfco / kQ,
    and must be always less than sr / 2. The bandwidth is measured
    between -3 dB points (i.e. amplitude gain = 0.7071), beyond which
    there is a +/- 6 dB / octave slope. This filter type is very similar
    to ar butterbp asig, kfco, kfco / kQ.

  * 6: band-reject filter, with the same parameters as the bandpass
    filter, and a response similar to that of butterbr.

  * 8: peaking EQ. It has an amplitude gain of 1 (0 dB) at 0 Hz and sr /
    2, and klvl at the center frequency (kfco). Thus, klvl controls the
    amount of boost (if it is greater than 1), or cut (if it is less
    than 1). Setting klvl to 1 results in a flat response. Similarly to
    the bandpass and band-reject filters, the bandwidth is determined by
    kfco / kQ (which must be less than sr / 2 again); however, this time
    it is between sqrt(klvl) points (or, in other words, half the boost
    or cut in decibels). NOTE: excessively low or high values of klvl
    should be avoided (especially with 32-bit floats), though the opcode
    was tested with klvl = 0.01 and klvl = 100. klvl = 0 is always an
    error, unlike in the case of pareq, which does allow a zero level.

  * 10: low shelf EQ, controlled by klvl and kS (kQ is ignored by this
    filter type). There is an amplitude gain of klvl at zero frequency,
    while the level of high frequencies (around sr / 2) is not changed.
    At the corner frequency (kfco), the gain is sqrt(klvl) (half the
    boost or cut in decibels). The kS parameter controls the steepness
    of the slope of the frequency response (see below).

  * 12: high shelf EQ. Very similar to the low shelf EQ, but affects the
    high frequency range.

The default value for imode is zero (lowpass filter, initialization not
skipped).

  Performance

ar -- the output signal.

asig -- the input signal

  NOTE

If the input contains silent sections, on Intel CPUs a significant
slowdown can occur due to denormals. In such cases, it is recommended to
process the input signal with "denorm" opcode before filtering it with
rbjeq (and actually many other filters).

kfco -- cutoff, corner, or center frequency, depending on filter type,
in Hz. It must be greater than zero, and less than sr / 2 (the range of
about sr * 0.0002 to sr * 0.49 should be safe).

klvl -- level (amount of boost or cut), as amplitude gain (e.g. 1: flat
response, 4: 12 dB boost, 0.1: 20 dB cut); zero or negative values are
not allowed. It is recognized by the peaking and shelving EQ types (8,
10, 12) only, and is ignored by other filters.

kQ -- resonance (also kfco / bandwidth in many filter types). Not used
by the shelving EQs (imode = 10 and 12). The exact meaning of this
parameter depends on the filter type (see above), but it should be
always greater than zero, and usually (kfco / kQ) less than sr / 2.

kS -- shelf slope parameter for shelving filters. Must be greater than
zero; a higher value means a steeper slope, with resonance if kS > 1
(however, a too high kS value may make the filter unstable). If kS is
set to exactly 1, the shelf slope is as steep as possible without a
resonance. Note that the effect of kS - especially if it is greater than
1 - also depends on klvl, and it does not have any well defined unit.


===========================================================================
readclock                                                         *readclock*

  Description

Reads the value of an internal clock.

  Syntax

ir readclock inum

  Initialization

inum -- the number of a clock. There are 32 clocks numbered 0 through
31. All other values are mapped to clock number 32.

ir -- value at i-time, of the clock specified by inum

  Performance

Between a clockon and a clockoff opcode, the CPU time used is
accumulated in the clock. The precision is machine dependent but is the
millisecond range on UNIX and Windows systems. The readclock opcde reads
the current value of a clock at initialization time.


===========================================================================
readf                                                                 *readf*

  Description

Read a line of text from an external file once each k-cycle.

  Syntax

Sres, kline readf ifilname

  Initialization

ifilname -- an integer N denoting a file named "input.N" or a character
string (in double quotes, spaces permitted) denoting the external file
name. For a string, it may either be a full path name with directory
specified or a simple filename. In the later case, the file is sought
first in the current directory, then in SSDIR, and finally in SFDIR.

  Performance

Sres -- output of the line read from ifilname.

kline -- line number, or -1 when end of file has been reached.

This opcode allows a line of text to be read from a named external file.
There may be any number of readf opcodes in an instrument or orchestra
but they read separately from the same or different files.


===========================================================================
readfi                                                               *readfi*

  Description

Read a line of text from an external file once on initialisation.

  Syntax

Sres, iline readfi ifilname

  Initialization

ifilname -- an integer N denoting a file named "input.N" or a character
string (in double quotes, spaces permitted) denoting the external file
name. For a string, it may either be a full path name with directory
specified or a simple filename. In the later case, the file is sought
first in the current directory, then in SSDIR, and finally in SFDIR.

iline -- line number, or -1 when end of file has been reached.

Sres -- output of the line read from ifilname.

This opcode allows a line of text to be read from a named external file.
There may be any number of readfi opcodes in an instrument or orchestra
but they read separately from the same or different files.


===========================================================================
readk                                                                 *readk*

  Description

Periodically reads an orchestra control-signal value from a named
external file in a specific format.

  Syntax

kres readk ifilname, iformat, iprd

  Initialization

ifilname -- an integer N denoting a file named "readk.N" or a character
string (in double quotes, spaces permitted) denoting the external file
name. For a string, it may either be a full path name with directory
specified or a simple filename. In the later case, the file is sought
first in the current directory, then in SSDIR, and finally in SFDIR.

iformat -- specifies the input data format:

  * 1 = 8-bit signed integers (char)

  * 4 = 16-bit short integers

  * 5 = 32-bit long integers

  * 6 = 32-bit floats

  * 7 = ASCII long integers (plain text)

  * 8 = ASCII floats (plain text)

Note that A-law and U-law formats are not available, and that all
formats except the last two are binary. The input file should be a
"raw", headerless data file.

iprd -- the rate (period) in seconds, rounded to the nearest orchestra
control period, at which the signal is read from the input file. A value
of 0 implies one control period (the enforced minimum), which will read
new values at the orchestra control rate. Longer periods will cause the
same values to repeat for more than one control period.

  Performance

kres -- output of the signal read from ifilname.

This opcode allows a generated control signal value to be read from a
named external file. The file should contain no header information but
it should contain a regularly sampled time series of control values. For
ASCII text formats, the values are assumed to be separated by at least
one whitespace character. There may be any number of readk opcodes in an
instrument or orchestra and they may read from the same or different files.


===========================================================================
readk2                                                               *readk2*

  Description

Periodically reads two orchestra control-signal values from an external
file.

  Syntax

kr1, kr2 readk2 ifilname, iformat, iprd

  Initialization

ifilname -- an integer N denoting a file named "readk.N" or a character
string (in double quotes, spaces permitted) denoting the external file
name. For a string, it may either be a full path name with directory
specified or a simple filename. In the later case, the file is sought
first in the current directory, then in SSDIR, and finally in SFDIR.

iformat -- specifies the input data format:

  * 1 = 8-bit signed integers (char)

  * 4 = 16-bit short integers

  * 5 = 32-bit long integers

  * 6 = 32-bit floats

  * 7 = ASCII long integers (plain text)

  * 8 = ASCII floats (plain text)

Note that A-law and U-law formats are not available, and that all
formats except the last two are binary. The input file should be a
"raw", headerless data file.

iprd -- the rate (period) in seconds, rounded to the nearest orchestra
control period, at which the signals are read from the input file. A
value of 0 implies one control period (the enforced minimum), which will
read new values at the orchestra control rate. Longer periods will cause
the same values to repeat for more than one control period.

  Performance

kr1, kr2 -- output of the signals read from ifilname.

This opcode allows two generated control signal values to be read from a
named external file. The file should contain no header information but
it should contain a regularly sampled time series of control values. For
binary formats, the individual samples of each signal are interleaved.
For ASCII text formats, the values are assumed to be separated by at
least one whitespace character. The two "channels" in a sample frame may
be on the same line or separated by newline characters, it does not
matter. There may be any number of readk2 opcodes in an instrument or
orchestra and they may read from the same or different files.


===========================================================================
readk3                                                               *readk3*

  Description

Periodically reads three orchestra control-signal values from an
external file.

  Syntax

kr1, kr2, kr3 readk3 ifilname, iformat, iprd

  Initialization

ifilname -- an integer N denoting a file named "readk.N" or a character
string (in double quotes, spaces permitted) denoting the external file
name. For a string, it may either be a full path name with directory
specified or a simple filename. In the later case, the file is sought
first in the current directory, then in SSDIR, and finally in SFDIR.

iformat -- specifies the input data format:

  * 1 = 8-bit signed integers (char)

  * 4 = 16-bit short integers

  * 5 = 32-bit long integers

  * 6 = 32-bit floats

  * 7 = ASCII long integers (plain text)

  * 8 = ASCII floats (plain text)

Note that A-law and U-law formats are not available, and that all
formats except the last two are binary. The input file should be a
"raw", headerless data file.

iprd -- the rate (period) in seconds, rounded to the nearest orchestra
control period, at which the signals are read from the input file. A
value of 0 implies one control period (the enforced minimum), which will
read new values at the orchestra control rate. Longer periods will cause
the same values to repeat for more than one control period.

  Performance

kr1, kr2, kr3 -- output of the signals read from ifilname.

This opcode allows three generated control signal values to be read from
a named external file. The file should contain no header information but
it should contain a regularly sampled time series of control values. For
binary formats, the individual samples of each signal are interleaved.
For ASCII text formats, the values are assumed to be separated by at
least one whitespace character. The three "channels" in a sample frame
may be on the same line or separated by newline characters, it does not
matter. There may be any number of readk3 opcodes in an instrument or
orchestra and they may read from the same or different files.


===========================================================================
readk4                                                               *readk4*

  Description

Periodically reads four orchestra control-signal values from an external
file.

  Syntax

kr1, kr2, kr3, kr4 readk4 ifilname, iformat, iprd

  Initialization

ifilname -- an integer N denoting a file named "readk.N" or a character
string (in double quotes, spaces permitted) denoting the external file
name. For a string, it may either be a full path name with directory
specified or a simple filename. In the later case, the file is sought
first in the current directory, then in SSDIR, and finally in SFDIR.

iformat -- specifies the input data format:

  * 1 = 8-bit signed integers (char)

  * 4 = 16-bit short integers

  * 5 = 32-bit long integers

  * 6 = 32-bit floats

  * 7 = ASCII long integers (plain text)

  * 8 = ASCII floats (plain text)

Note that A-law and U-law formats are not available, and that all
formats except the last two are binary. The input file should be a
"raw", headerless data file.

iprd -- the rate (period) in seconds, rounded to the nearest orchestra
control period, at which the signals are read from the input file. A
value of 0 implies one control period (the enforced minimum), which will
read new values at the orchestra control rate. Longer periods will cause
the same values to repeat for more than one control period.

  Performance

kr1, kr2, kr3, kr4 -- output of the signals read from ifilname.

This opcode allows four generated control signal values to be read from
a named external file. The file should contain no header information but
it should contain a regularly sampled time series of control values. For
binary formats, the individual samples of each signal are interleaved.
For ASCII text formats, the values are assumed to be separated by at
least one whitespace character. The four "channels" in a sample frame
may be on the same line or separated by newline characters, it does not
matter. There may be any number of readk4 opcodes in an instrument or
orchestra and they may read from the same or different files.


===========================================================================
readscore                                                         *readscore*

  Description

Readscore will issue one or more score events. It can handle strings in
the same conditions as the standard score, including preprocessing
(carry, sort, ramp, etc). Multi-line strings are accepted, using {{ }}
to enclose the string.

  Syntax

readscore Sin 

  Initialization

“Sin” -- a string (in double-quotes or enclosed by {{ }}) containing one
or more score events.


===========================================================================
readscratch                                                     *readscratch*

  Description

The readscratch opcode returns one of four scalar values stored in the
instance of an instrument.

  Syntax

ival readscratch[index]

  Initialisation

ival -- variable for result.

index -- which value to read, defaulting to zero.


===========================================================================
rect2pol                                                           *rect2pol*

  Description

Converts an input array in real-imaginary format to magnitude-phase format.

  Syntax

kout[] rect2pol kin[]

  Performance

kout[] -- output array containing the complex-valued magnitude-phase
output. It will be created if it does not exist.

kin[] -- input array containing the complex-valued real-imaginary input.


===========================================================================
reinit                                                               *reinit*

  Description

Suspends a performance while a special initialization pass is executed.

Whenever this statement is encountered during a p-time pass, performance
is temporarily suspended while a special Initialization pass, beginning
at label and continuing to rireturn or endin, is executed. Performance
will then be resumed from where it left off.

  Syntax

reinit label


===========================================================================
release                                                             *release*

  Description

Provides a way of knowing when a note off message for the current note
is received. Only a noteoff message with the same MIDI note number as
the one which triggered the note will be reported by release.

  Syntax

kflag release

  Performance

kflag -- indicates whether the note is in its “release” stage. (1 if a
note off is received, otherwise 0)

release outputs current note state. If current note is in the “release”
stage (i.e. if its duration has been extended with xtratim opcode and if
it has only just deactivated), then the kflag output argument is set to
1. Otherwise (in sustain stage of current note), kflag is set to 0.

This opcode is useful for implementing complex release-oriented
envelopes. When used in conjunction with xtratim it can provide an
alternative to the hard-coded behaviour of the "r" opcodes (linsegr,
expsegr et al), where release time is set to the longest time specified
in the active instrument.


===========================================================================
remoteport                                                       *remoteport*

  Description

Defines the port for use with the insremot, midremot, insglobal and
midglobal opcodes.

  Syntax

remoteport iportnum

  Initialization

iportnum -- number of the port to be used. If zero or negative the
default port 40002 is selected.


===========================================================================
remove                                                               *remove*

  Description

Removes the definition of an instrument as long as it is not in use.

  Syntax

remove insnum

  Initialization

insnum -- number or name of the instrument to be deleted

  Performance

As long as the indicated instrument is not active, remove deletes the
instrument and memory associated with it. It should be treated with care
as it is possible that in some cases its use may lead to a crash.


===========================================================================
repluck                                                             *repluck*

  Description

repluck is an implementation of the physical model of the plucked
string. A user can control the pluck point, the pickup point, the
filter, and an additional audio signal, axcite. axcite is used to excite
the 'string'. Based on the Karplus-Strong algorithm.

  Syntax

ares repluck iplk, kamp, icps, kpick, krefl, axcite

  Initialization

iplk -- The point of pluck is iplk, which is a fraction of the way up
the string (0 to 1). A pluck point of zero means no initial pluck.

icps -- The string plays at icps pitch.

  Performance

kamp -- Amplitude of note.

kpick -- Proportion of the way along the string to sample the output.

krefl -- the coefficient of reflection, indicating the lossiness and the
rate of decay. It must be strictly between 0 and 1 (it will complain
about both 0 and 1).

  Performance

axcite -- A signal which excites the string.


===========================================================================
reson                                                                 *reson*

  Description

A second-order resonant filter.

  Syntax

ares reson asig, xcf, xbw [, iscl] [, iskip]

  Initialization

iscl (optional, default=0) -- coded scaling factor for resonators. A
value of 1 signifies a peak response factor of 1, i.e. all frequencies
other than kcf are attenuated in accordance with the (normalized)
response curve. A value of 2 raises the response factor so that its
overall RMS value equals 1. (This intended equalization of input and
output power assumes all frequencies are physically present; hence it is
most applicable to white noise.) A zero value signifies no scaling of
the signal, leaving that to some later adjustment (see balance). The
default value is 0.

iskip (optional, default=0) -- initial disposition of internal data
space. Since filtering incorporates a feedback loop of previous output,
the initial status of the storage space used is significant. A zero
value will clear the space; a non-zero value will allow previous
information to remain. The default value is 0.

  Performance

ares -- the output signal at audio rate.

asig -- the input signal at audio rate.

xcf -- the center frequency of the filter, or frequency position of the
peak response.

xbw -- bandwidth of the filter (the Hz difference between the upper and
lower half-power points).

reson is a second-order filter in which kcf controls the center
frequency, or frequency position of the peak response, and kbw controls
its bandwidth (the frequency difference between the upper and lower
half-power points).


===========================================================================
resonk                                                               *resonk*

  Description

A second-order resonant filter.

  Syntax

kres resonk ksig, kcf, kbw [, iscl] [, iskip]

  Initialization

iscl (optional, default=0) -- coded scaling factor for resonators. A
value of 1 signifies a peak response factor of 1, i.e. all frequencies
other than kcf are attenuated in accordance with the (normalized)
response curve. A value of 2 raises the response factor so that its
overall RMS value equals 1. (This intended equalization of input and
output power assumes all frequencies are physically present; hence it is
most applicable to white noise.) A zero value signifies no scaling of
the signal, leaving that to some later adjustment (see balance). The
default value is 0.

iskip (optional, default=0) -- initial disposition of internal data
space. Since filtering incorporates a feedback loop of previous output,
the initial status of the storage space used is significant. A zero
value will clear the space; a non-zero value will allow previous
information to remain. The default value is 0.

  Performance

kres -- the output signal at control-rate.

ksig -- the input signal at control-rate.

kcf -- the center frequency of the filter, or frequency position of the
peak response.

kbw -- bandwidth of the filter (the Hz difference between the upper and
lower half-power points).

resonk is like reson except its output is at control-rate rather than
audio rate.


===========================================================================
resonr                                                               *resonr*

  Description

Implementations of a second-order, two-pole two-zero bandpass filter
with variable frequency response.

  Syntax

ares resonr asig, xcf, xbw [, iscl] [, iskip]

  Initialization

The optional initialization variables for resonr are identical to the
i-time variables for reson.

iscl (optional, default=0) -- coded scaling factor for resonators. A
value of 1 signifies a peak response factor of 1, i.e. all frequencies
other than kcf are attenuated in accordance with the (normalized)
response curve. A value of 2 raises the response factor so that its
overall RMS value equals 1. This intended equalization of input and
output power assumes all frequencies are physically present; hence it is
most applicable to white noise. A zero value signifies no scaling of the
signal, leaving that to some later adjustment (see balance). The default
value is 0.

iskip (optional, default=0) -- initial disposition of internal data
space. Since filtering incorporates a feedback loop of previous output,
the initial status of the storage space used is significant. A zero
value will clear the space; a non-zero value will allow previous
information to remain. The default value is 0.

  Performance

asig -- input signal to be filtered

xcf -- cutoff or resonant frequency of the filter, measured in Hz

xbw -- bandwidth of the filter (the Hz difference between the upper and
lower half-power points)

resonr and resonz are variations of the classic two-pole bandpass
resonator (reson). Both filters have two zeroes in their transfer
functions, in addition to the two poles. resonz has its zeroes located
at z = 1 and z = -1. resonr has its zeroes located at +sqrt(R) and
-sqrt(R), where R is the radius of the poles in the complex z-plane. The
addition of zeroes to resonr and resonz results in the improved
selectivity of the magnitude response of these filters at cutoff
frequencies close to 0, at the expense of less selectivity of
frequencies above the cutoff peak.

resonr and resonz are very close to constant-gain as the center
frequency is swept, resulting in a more efficient control of the
magnitude response than with traditional two-pole resonators such as reson.

resonr and resonz produce a sound that is considerably different from
reson, especially for lower center frequencies; trial and error is the
best way of determining which resonator is best suited for a particular
application.


===========================================================================
resonx                                                               *resonx*

  Description

resonx is equivalent to a filters consisting of more layers of reson
with the same arguments, serially connected. Using a stack of a larger
number of filters allows a sharper cutoff. They are faster than using a
larger number instances in a Csound orchestra of the old opcodes,
because only one initialization and k- cycle are needed at time and the
audio loop falls entirely inside the cache memory of processor.

  Syntax

ares resonx asig, xcf, xbw [, inumlayer] [, iscl] [, iskip]

  Initialization

inumlayer (optional) -- number of elements in the filter stack. Default
value is 4.

iscl (optional, default=0) -- coded scaling factor for resonators. A
value of 1 signifies a peak response factor of 1, i.e. all frequencies
other than kcf are attenuated in accordance with the (normalized)
response curve. A value of 2 raises the response factor so that its
overall RMS value equals 1. (This intended equalization of input and
output power assumes all frequencies are physically present; hence it is
most applicable to white noise.) A zero value signifies no scaling of
the signal, leaving that to some later adjustment (see balance). The
default value is 0.

iskip (optional, default=0) -- initial disposition of internal data
space. Since filtering incorporates a feedback loop of previous output,
the initial status of the storage space used is significant. A zero
value will clear the space; a non-zero value will allow previous
information to remain. The default value is 0.

  Performance

asig -- input signal

xcf -- the center frequency of the filter, or frequency position of the
peak response.

xbw -- bandwidth of the filter (the Hz difference between the upper and
lower half-power points)


===========================================================================
resonxk                                                             *resonxk*

  Description

resonxk is equivalent to a group of resonk filters, with the same
arguments, serially connected. Using a stack of a larger number of
filters allows a sharper cutoff.

  Syntax

kres resonxk ksig, kcf, kbw[, inumlayer, iscl, istor]

  Initialization

inumlayer - number of elements of filter stack. Default value is 4.
Maximum value is 10

iscl (optional, default=0) - coded scaling factor for resonators. A
value of 1 signifies a peak response factor of 1, i.e. all frequencies
other than kcf are attenuated in accordance with the (normalized)
response curve. A value of 2 raises the response factor so that its
overall RMS value equals 1. (This intended equalization of input and
output power assumes all frequencies are physically present; hence it is
most applicable to white noise.) A zero value signifies no scaling of
the signal, leaving that to some later adjustment (see balance). The
default value is 0.

istor (optional, default=0) -- initial disposition of internal data
space. Since filtering incorporates a feedback loop of previous output,
the initial status of the storage space used is significant. A zero
value will clear the space; a non-zero value will allow previous
information to remain. The default value is 0.

  Performance

kres - output signal

ksig - input signal

kcf - the center frequency of the filter, or frequency position of the
peak response.

kbw - bandwidth of the filter (the Hz difference between the upper and
lower half-power points)

resonxk is a lot faster than using individual instances in Csound
orchestra of the old opcodes, because only one initialization and 'k'
cycle are needed at a time, and the audio loop falls enterely inside the
cache memory of processor.


===========================================================================
resony                                                               *resony*

  Description

A bank of second-order bandpass filters, connected in parallel.

  Syntax

ares resony asig, kbf, kbw, inum, ksep [, isepmode] [, iscl] [, iskip]

  Initialization

inum -- number of filters

isepmode (optional, default=0) -- if isepmode = 0, the separation of
center frequencies of each filter is generated logarithmically (using
octave as unit of measure). If isepmode not equal to 0, the separation
of center frequencies of each filter is generated linearly (using
Hertz). Default value is 0.

iscl (optional, default=0) -- coded scaling factor for resonators. A
value of 1 signifies a peak response factor of 1, i.e. all frequencies
other than kcf are attenuated in accordance with the (normalized)
response curve. A value of 2 raises the response factor so that its
overall RMS value equals 1. (This intended equalization of input and
output power assumes all frequencies are physically present; hence it is
most applicable to white noise.) A zero value signifies no scaling of
the signal, leaving that to some later adjustment (e.g. balance). The
default value is 0.

iskip (optional, default=0) -- initial disposition of internal data
space. Since filtering incorporates a feedback loop of previous output,
the initial status of the storage space used is significant. A zero
value will clear the space; a non-zero value will allow previous
information to remain. The default value is 0.

  Performance

asig -- audio input signal

kbf -- base frequency, i.e. center frequency of lowest filter in Hz

kbw -- bandwidth in Hz

ksep -- separation of the center frequency of filters in octaves

resony is a bank of second-order bandpass filters, with k-rate variant
frequency separation, base frequency and bandwidth, connected in
parallel (i.e. the resulting signal is a mix of the output of each
filter). The center frequency of each filter depends of kbf and ksep
variables. The maximum number of filters is set to 100.


===========================================================================
resonz                                                               *resonz*

  Description

Implementations of a second-order, two-pole two-zero bandpass filter
with variable frequency response.

  Syntax

ares resonz asig, xcf, xbw [, iscl] [, iskip]

  Initialization

The optional initialization variables for resonr and resonz are
identical to the i-time variables for reson.

iskip -- initial disposition of internal data space. Since filtering
incorporates a feedback loop of previous output, the initial status of
the storage space used is significant. A zero value will clear the
space; a non-zero value will allow previous information to remain. The
default value is 0.

iscl -- coded scaling factor for resonators. A value of 1 signifies a
peak response factor of 1, i.e. all frequencies other than kcf are
attenuated in accordance with the (normalized) response curve. A value
of 2 raises the response factor so that its overall RMS value equals 1.
This intended equalization of input and output power assumes all
frequencies are physically present; hence it is most applicable to white
noise. A zero value signifies no scaling of the signal, leaving that to
some later adjustment (see balance). The default value is 0.

  Performance

resonr and resonz are variations of the classic two-pole bandpass
resonator (reson). Both filters have two zeroes in their transfer
functions, in addition to the two poles. resonz has its zeroes located
at z = 1 and z = -1. resonr has its zeroes located at +sqrt(R) and
-sqrt(R), where R is the radius of the poles in the complex z-plane. The
addition of zeroes to resonr and resonz results in the improved
selectivity of the magnitude response of these filters at cutoff
frequencies close to 0, at the expense of less selectivity of
frequencies above the cutoff peak.

resonr and resonz are very close to constant-gain as the center
frequency is swept, resulting in a more efficient control of the
magnitude response than with traditional two-pole resonators such as reson.

resonr and resonz produce a sound that is considerably different from
reson, especially for lower center frequencies; trial and error is the
best way of determining which resonator is best suited for a particular
application.

asig -- input signal to be filtered

xcf -- cutoff or resonant frequency of the filter, measured in Hz

xbw -- bandwidth of the filter (the Hz difference between the upper and
lower half-power points)

Technical History

resonr and resonz were originally described in an article by Julius O.
Smith and James B. Angell.^1 Smith and Angell recommended the resonz
form (zeros at +1 and -1) when computational efficiency was the main
concern, as it has one less multiply per sample, while resonr (zeroes at
+ and - the square root of the pole radius R) was recommended for
situations when a perfectly constant-gain center peak was required.

Ken Steiglitz, in a later article ^2 , demonstrated that resonz had
constant gain at the true peak of the filter, as opposed to resonr,
which displayed constant gain at the pole angle. Steiglitz also
recommended resonz for its sharper notches in the gain curve at zero and
Nyquist frequency. Steiglitz's recent book ^3 features a thorough
technical discussion of reson and resonz, while Dodge and Jerse's
textbook ^4 illustrates the differences in the response curves of reson
and resonz.


===========================================================================
resyn                                                                 *resyn*

  Description

The resyn opcode takes an input containg a TRACKS pv streaming signal
(as generated, for instance by partials). It resynthesises the signal
using linear amplitude and cubic phase interpolation to drive a bank of
interpolating oscillators with amplitude and pitch scaling controls.
Resyn is a modified version of sinsyn, allowing for the resynthesis of
data with pitch and timescale changes.

  Syntax

asig resyn fin, kscal, kpitch, kmaxtracks, ifn

  Performance

asig -- output audio rate signal

fin -- input pv stream in TRACKS format

kscal -- amplitude scaling

kpitch -- pitch scaling

kmaxtracks -- max number of tracks in resynthesis. Limiting this will
cause a non-linear filtering effect, by discarding newer and
higher-frequency tracks (tracks are ordered by start time and ascending
frequency, respectively)

ifn -- function table containing one cycle of a sinusoid (sine or cosine)


===========================================================================
return                                                               *return*

  Description

Return will return a value from an instrument at i-time. The value of a
global instrument (instrument 0) can be retrieved after compilation by
the evalstr opcode. The retrieval of values returned by other
instruments is not yet implemented.

  Syntax

return ival 

  Initialization

“ival” -- a value to be returned by instrument.


===========================================================================
reverb                                                               *reverb*

  Description

Reverberates an input signal with a “natural room” frequency response.

  Syntax

ares reverb asig, krvt [, iskip]

  Initialization

iskip (optional, default=0) -- initial disposition of delay-loop data
space (cf. reson). The default value is 0.

  Performance

krvt -- the reverberation time (defined as the time in seconds for a
signal to decay to 1/1000, or 60dB down from its original amplitude).

A standard reverb unit is composed of four comb filters in parallel
followed by two alpass units in series. Loop times are set for optimal
“natural room response.” Core storage requirements for this unit are
proportional only to the sampling rate, each unit requiring
approximately 3K words for every 10KC. The comb, alpass, delay, tone and
other Csound units provide the means for experimenting with alternate
reverberator designs.

Since output from the standard reverb will begin to appear only after
1/20 second or so of delay, and often with less than three-fourths of
the original power, it is normal to output both the source and the
reverberated signal. If krvt is inadvertently set to a non-positive
number, krvt will be reset automatically to 0.01. (New in Csound version
4.07.) Also, since the reverberated sound will persist long after the
cessation of source events, it is normal to put reverb in a separate
instrument to which sound is passed via a global variable, and to leave
that instrument running throughout the performance.


===========================================================================
reverb2                                                             *reverb2*

  Description

Same as the nreverb opcode.

  Syntax

ares reverb2 asig, ktime, khdif [, iskip] [,inumCombs] \
      [, ifnCombs] [, inumAlpas] [, ifnAlpas]

===========================================================================
reverbsc                                                           *reverbsc*

  Description

8 delay line stereo FDN reverb, with feedback matrix based upon physical
modeling scattering junction of 8 lossless waveguides of equal
characteristic impedance. Based on Csound orchestra version by Sean
Costello.

  Syntax

aoutL, aoutR reverbsc ainL, ainR, kfblvl, kfco[, israte[, ipitchm[, iskip]]] 

  Initialization

israte (optional, defaults to the orchestra sample rate) -- assume a
sample rate of israte. This is normally set to sr, but a different
setting can be useful for special effects.

ipitchm (optional, defaults to 1) -- depth of random variation added to
delay times, in the range 0 to 10. The default is 1, but this may be too
high and may need to be reduced for held pitches such as piano tones.

iskip (optional, defaults to zero) -- if non-zero, initialization of the
opcode is skipped, whenever possible.

  Performance

aoutL, aoutR -- output signals for left and right channel

ainL, ainR -- left and right channel input. Note that having an input
signal on either the left or right channel only will still result in
having reverb output on both channels, making this unit more suitable
for reverberating stereo input than the freeverb opcode.

kfblvl -- feedback level, in the range 0 to 1. 0.6 gives a good small
"live" room sound, 0.8 a small hall, and 0.9 a large hall. A setting of
exactly 1 means infinite length, while higher values will make the
opcode unstable.

kfco -- cutoff frequency of simple first order lowpass filters in the
feedback loop of delay lines, in Hz. Should be in the range 0 to
israte/2 (not sr/2). A lower value means faster decay in the high
frequency range.


===========================================================================
rewindscore                                                     *rewindscore*

  Description

Rewinds the playback position of the current score performance..

  Syntax

 rewindscore


===========================================================================
rezzy                                                                 *rezzy*

  Description

A resonant low-pass filter.

  Syntax

ares rezzy asig, xfco, xres [, imode, iskip]

  Initialization

imode (optional, default=0) -- high-pass or low-pass mode. If zero,
rezzy is low-pass. If not zero, rezzy is high-pass. Default value is 0.
(New in Csound version 3.50)

iskip (optional, default=0) -- if non zero skip the initialisation of
the filter. (New in Csound version 4.23f13 and 5.0)

  Performance

asig -- input signal

xfco -- filter cut-off frequency in Hz. As of version 3.50, may i-,k-,
or a-rate.

xres -- amount of resonance. Values of 1 to 100 are typical. Resonance
should be one or greater. As of version 3.50, may a-rate, i-rate, or
k-rate.

rezzy is a resonant low-pass filter created empirically by Hans Mikelson.


===========================================================================
rfft                                                                   *rfft*

  Description

Applies a forward Fast Fourier Transform to a real-value input
1-dimensional array. The output is another array containing the
transform, non-redundant, non-negative spectrum only. If the input array
is power-of-two, the output array size will match the input size, with
the first two points containing 0Hz and Nyquist frequency coefficients.
Otherwise, the output will have two extra values (input size + 2), and
the the Nyquist coefficient will be placed at kin[input_size] position
(kin[1] and kin[input_size+1] will be 0].

  Syntax

kout[] rfft kin[]

  Performance

kout[] -- output array containing the transform. It will be created if
it does not exist.

kin[] -- input array containing the real-valued input.


===========================================================================
rifft                                                                 *rifft*

  Description

Applies an Inverse Fast Fourier Transform to a complex-value input
1-dimensional array producing a real-valued output. The output is
another array containing the real-valued signal. If the input array is
power-of-two, the output array size will match the input size.
Otherwise, the output will have two fewer values (input size - 2).

  Syntax

kout[] rifft kin[]

  Performance

kout[] -- output array containing the real-valued output. It will be
created if it does not exist.

kin[] -- input array containing the complex input.


===========================================================================
rigoto                                                               *rigoto*

  Description

Similar to igoto, but effective only during a reinit pass (i.e., no-op
at standard i-time). This statement is useful for bypassing units that
are not to be reinitialized.

  Syntax

rigoto label


===========================================================================
rireturn                                                           *rireturn*

  Description

Terminates a reinit pass (i.e., no-op at standard i-time). This
statement, or an endin, will cause normal performance to be resumed.

  Syntax

rireturn


===========================================================================
rms                                                                     *rms*

  Description

Determines the root-mean-square amplitude of an audio signal. It
low-pass filters the actual value, to average in the manner of a VU meter.

  Syntax

kres rms asig [, ihp] [, iskip]

  Initialization

ihp (optional, default=10) -- half-power point (in Hz) of a special
internal low-pass filter. The default value is 10.

iskip (optional, default=0) -- initial disposition of internal data
space (see reson). The default value is 0.

  Performance

asig -- input audio signal

kres -- low-pass filtered rms value of the input signal

rms output values kres will trace the root-mean-square value of the
audio input asig. This unit is not a signal modifier, but functions
rather as a signal power-gauge. It uses an internal low-pass filter to
make the response smoother. ihp can be used to control this smoothing.
The higher the value, the "snappier" the measurement.

This opcode can also be used as an evelope follower.

The kres output from this opcode is given in amplitude and depends on
0dbfs. If you want the output in decibels, you can use dbamp


===========================================================================
rnd                                                                     *rnd*

  Description

Returns a random number in a unipolar range at the rate given by the
input argument.

  Syntax

rnd(x) (init- or control-rate only)

Where the argument within the parentheses may be an expression. These
value converters sample a global random sequence, but do not reference
seed. The result can be a term in a further expression.

  Performance

Returns a random number in the unipolar range 0 to x.


===========================================================================
rnd31                                                                 *rnd31*

  Description

31-bit bipolar random opcodes with controllable distribution. These
units are portable, i.e. using the same seed value will generate the
same random sequence on all systems. The distribution of generated
random numbers can be varied at k-rate.

  Syntax

ax rnd31 kscl, krpow [, iseed]

ix rnd31 iscl, irpow [, iseed]

kx rnd31 kscl, krpow [, iseed]

  Initialization

ix -- i-rate output value.

iscl -- output scale. The generated random numbers are in the range
-iscl to iscl.

irpow -- controls the distribution of random numbers. If irpow is
positive, the random distribution (x is in the range -1 to 1) is abs(x)
^ ((1 / irpow) - 1); for negative irpow values, it is (1 - abs(x)) ^
((-1 / irpow) - 1). Setting irpow to -1, 0, or 1 will result in uniform
distribution (this is also faster to calculate).

[A graph of distributions for different values of irpow.]

A graph of distributions for different values of irpow.

iseed (optional, default=0) -- seed value for random number generator
(positive integer in the range 1 to 2147483646 (2 ^ 31 - 2)). Zero or
negative value seeds from current time (this is also the default).
Seeding from current time is guaranteed to generate different random
sequences, even if multiple random opcodes are called in a very short time.

In the a- and k-rate version the seed is set at opcode initialization.
With i-rate output, if iseed is zero or negative, it will seed from
current time in the first call, and return the next value from the
random sequence in successive calls; positive seed values are set at all
i-rate calls. The seed is local for a- and k-rate, and global for i-rate
units.

  Notes

  * although seed values up to 2147483646 are allowed, it is recommended
    to use smaller numbers (< 1000000) for portability, as large
    integers may be rounded to a different value if 32-bit floats are used.

  * i-rate rnd31 with a positive seed will always produce the same
    output value (this is not a bug). To get different values, set seed
    to 0 in successive calls, which will return the next value from the
    random sequence.

  Performance

ax -- a-rate output value.

kx -- k-rate output value.

kscl -- output scale. The generated random numbers are in the range
-kscl to kscl. It is the same as iscl, but can be varied at k-rate.

krpow -- controls the distribution of random numbers. It is the same as
irpow, but can be varied at k-rate.


===========================================================================
round                                                                 *round*

  Description

The integer value nearest to x ; if the fractional part of x is exactly
0.5, the direction of rounding is undefined.

  Syntax

round(x) (init-, control-, or audio-rate arg allowed)

where the argument within the parentheses may be an expression. Value
converters perform arithmetic translation from units of one kind to
units of another. The result can then be a term in a further expression.


===========================================================================
rspline                                                             *rspline*

  Description

Generate random spline curves.

  Syntax

ares rspline xrangeMin, xrangeMax, kcpsMin, kcpsMax

kres rspline krangeMin, krangeMax, kcpsMin, kcpsMax

  Performance

kres, ares -- Output signal

xrangeMin, xrangeMax -- Range of values of random-generated points

kcpsMin, kcpsMax -- Range of point-generation rate. Min and max limits
are expressed in cps.

rspline (random-spline-curve generator) is similar to jspline but output
range is defined by means of two limit values. Also in this case, real
output range could be a bit greater of range values, because of
interpolating curves beetween each pair of random-points.

At present time generated curves are quite smooth when cpsMin is not too
different from cpsMax. When cpsMin-cpsMax interval is big, some little
discontinuity could occurr, but it should not be a problem, in most
cases. Maybe the algorithm will be improved in next versions.

These opcodes are often better than jitter when user wants to
“naturalize” or “analogize” digital sounds. They could be used also in
algorithmic composition, to generate smooth random melodic lines when
used together with samphold opcode.

Note that the result is quite different from the one obtained by
filtering white noise, and they allow the user to obtain a much more
precise control.


===========================================================================
rtclock                                                             *rtclock*

  Description

Read the real-time clock from the operating system.

  Syntax

ires rtclock

kres rtclock

  Performance

Read the real-time clock from operating system. Under Windows, this
changes only once per second. Under GNU/Linux, it ticks every
microsecond. Performance under other systems varies.


===========================================================================
S                                                                         *S*

  Description

Returns a string containg the numeric value of its argument.

  Syntax

S(x) (control-rate or init-rate arg)


===========================================================================
s16b14                                                               *s16b14*

  Description

Creates a bank of 16 different 14-bit MIDI control message numbers.

  Syntax

i1,...,i16 s16b14 ichan, ictlno_msb1, ictlno_lsb1, imin1, imax1, \
      initvalue1, ifn1,..., ictlno_msb16, ictlno_lsb16, imin16, imax16, initvalue16, ifn16

k1,...,k16 s16b14 ichan, ictlno_msb1, ictlno_lsb1, imin1, imax1, \
      initvalue1, ifn1,..., ictlno_msb16, ictlno_lsb16, imin16, imax16, initvalue16, ifn16

  Initialization

i1 ... i64 -- output values

ichan -- MIDI channel (1-16)

ictlno_msb1 .... ictlno_msb32 -- MIDI control number, most significant
byte (0-127)

ictlno_lsb1 .... ictlno_lsb32 -- MIDI control number, least significant
byte (0-127)

imin1 ... imin64 -- minimum values for each controller

imax1 ... imax64 -- maximum values for each controller

init1 ... init64 -- initial value for each controller

ifn1 ... ifn64 -- function table for conversion for each controller

  Performance

k1 ... k64 -- output values

s16b14 is a bank of MIDI controllers, useful when using MIDI mixer such
as Kawai MM-16 or others for changing whatever sound parameter in
real-time. The raw MIDI control messages at the input port are converted
to agree with iminN and imaxN, and an initial value can be set. Also, an
optional non-interpolated function table with a custom translation curve
is allowed, useful for enabling exponential response curves.

When no function table translation is required, set the ifnN value to 0,
else set ifnN to a valid function table number. When table translation
is enabled (i.e. setting ifnN value to a non-zero number referring to an
already allocated function table), initN value should be set equal to
iminN or imaxN value, else the initial output value will not be the same
as specified in initN argument.

s16b14 allows a bank of 16 different MIDI control message numbers. It
uses 14-bit values instead of MIDI's normal 7-bit values.

As the input and output arguments are many, you can split the line using
'\' (backslash) character (new in 3.47 version) to improve the
readability. Using these opcodes is considerably more efficient than
using the separate ones (ctrl7 and tonek) when more controllers are
required.

In the i-rate version of s16b14, there is not an initial value input
argument. The output is taken directly from the current status of
internal controller array of Csound.


===========================================================================
s32b14                                                               *s32b14*

  Description

Creates a bank of 32 different 14-bit MIDI control message numbers.

  Syntax

i1,...,i32 s32b14 ichan, ictlno_msb1, ictlno_lsb1, imin1, imax1, \
      initvalue1, ifn1,..., ictlno_msb32, ictlno_lsb32, imin32, imax32, initvalue32, ifn32

k1,...,k32 s32b14 ichan, ictlno_msb1, ictlno_lsb1, imin1, imax1, \
      initvalue1, ifn1,..., ictlno_msb32, ictlno_lsb32, imin32, imax32, initvalue32, ifn32

  Initialization

i1 ... i64 -- output values

ichan -- MIDI channel (1-16)

ictlno_msb1 .... ictlno_msb32 -- MIDI control number, most significant
byte (0-127)

ictlno_lsb1 .... ictlno_lsb32 -- MIDI control number, least significant
byte (0-127)

imin1 ... imin64 -- minimum values for each controller

imax1 ... imax64 -- maximum values for each controller

init1 ... init64 -- initial value for each controller

ifn1 ... ifn64 -- function table for conversion for each controller

  Performance

k1 ... k64 -- output values

s32b14 is a bank of MIDI controllers, useful when using MIDI mixer such
as Kawai MM-16 or others for changing whatever sound parameter in
real-time. The raw MIDI control messages at the input port are converted
to agree with iminN and imaxN, and an initial value can be set. Also, an
optional non-interpolated function table with a custom translation curve
is allowed, useful for enabling exponential response curves.

When no function table translation is required, set the ifnN value to 0,
else set ifnN to a valid function table number. When table translation
is enabled (i.e. setting ifnN value to a non-zero number referring to an
already allocated function table), initN value should be set equal to
iminN or imaxN value, else the initial output value will not be the same
as specified in initN argument.

s32b14 allows a bank of 32 different MIDI control message numbers. It
uses 14-bit values instead of MIDI's normal 7-bit values.

As the input and output arguments are many, you can split the line using
'\' (backslash) character (new in 3.47 version) to improve the
readability. Using these opcodes is considerably more efficient than
using the separate ones (ctrl7 and tonek) when more controllers are
required.

In the i-rate version of s32b14, there is not an initial value input
argument. The output is taken directly from the current status of
internal controller array of Csound.


===========================================================================
samphold                                                           *samphold*

  Description

Performs a sample-and-hold operation on its input.

  Syntax

ares samphold asig, agate [, ival] [, ivstor]

kres samphold ksig, kgate [, ival] [, ivstor]

  Initialization

ival, ivstor (optional) -- controls initial disposition of internal save
space. If ivstor is zero the internal “hold” value is set to ival ; else
it retains its previous value. Defaults are 0,0 (i.e. init to zero)

  Performance

kgate, xgate -- controls whether to hold the signal.

samphold performs a sample-and-hold operation on its input according to
the value of gate. If gate != 0, the input samples are passed to the
output; if gate = 0, the last output value is repeated. The controlling
gate can be a constant, a control signal, or an audio signal.


===========================================================================
sandpaper                                                         *sandpaper*

  Description

sandpaper is a semi-physical model of a sandpaper sound. It is one of
the PhISEM percussion opcodes. PhISEM (Physically Informed Stochastic
Event Modeling) is an algorithmic approach for simulating collisions of
multiple independent sound producing objects.

  Syntax

ares sandpaper iamp, idettack [, inum] [, idamp] [, imaxshake]

  Initialization

iamp -- Amplitude of output. Note: As these instruments are stochastic,
this is only a approximation.

idettack -- period of time over which all sound is stopped

inum (optional) -- The number of beads, teeth, bells, timbrels, etc. If
zero, the default value is 128.

idamp (optional) -- the damping factor, as part of this equation:

damping_amount = 0.998 + (idamp * 0.002)

The default damping_amount is 0.999 which means that the default value
of idamp is 0.5. The maximum damping_amount is 1.0 (no damping). This
means the maximum value for idamp is 1.0.

The recommended range for idamp is usually below 75% of the maximum value.

imaxshake (optional) -- amount of energy to add back into the system.
The value should be in range 0 to 1.


===========================================================================
scale                                                                 *scale*

  Description

Scales incoming value to user-definable range. Similar to scale object
found in popular dataflow languages.

  Syntax

kscl scale kinput, kmax, kmin

  Performance

kin -- Input value. Can originate from any k-rate source as long as that
source's output is in range 0-1.

kmin -- Minimum value of the resultant scale operation.

kmax -- Maximum value of the resultant scale operation.


===========================================================================
scalearray                                                       *scalearray*

  Description

The scalearray opcode scales a subregion of a vector to a given
minimum/maximum.

  Syntax

scalearray tarray, kmin, kmax[, kleft, kright]

  Performance

karray -- array for operation.

kmin, kmax -- target minimum and maximum values.

kleft, kright -- range of table to use, defaulting to 0 and size of the
vector.


===========================================================================
scanhammer                                                       *scanhammer*

  Description

This is is a variant of tablecopy, copying from one table to another,
starting at ipos, and with a gain control. The number of points copied
is determined by the length of the source. Other points are not changed.
This opcode can be used to “hit” a string in the scanned synthesis code.

  Syntax

scanhammer isrc, idst, ipos, imult

  Initialization

isrc -- source function table.

idst -- destination function table.

ipos -- starting position (in points).

imult -- gain multiplier. A value of 0 will leave values unchanged.


===========================================================================
scans                                                                 *scans*

  Description

Generate audio output using scanned synthesis.

  Syntax

ares scans kamp, kfreq, ifn, id [, iorder]

  Initialization

ifn -- ftable containing the scanning trajectory. This is a series of
numbers that contains addresses of masses. The order of these addresses
is used as the scan path. It should not contain values greater than the
number of masses, or negative numbers. See the introduction to the
scanned synthesis section.

id -- ID number of the scanu opcode's waveform to use

iorder (optional, default=0) -- order of interpolation used internally.
It can take any value in the range 1 to 4, and defaults to 4, which is
quartic interpolation. The setting of 2 is quadratic and 1 is linear.
The higher numbers are slower, but not necessarily better.

  Performance

kamp -- output amplitude. Note that the resulting amplitude is also
dependent on instantaneous value in the wavetable. This number is
effectively the scaling factor of the wavetable.

kfreq -- frequency of the scan rate


===========================================================================
scantable                                                         *scantable*

  Description

A simpler scanned synthesis implementation. This is an implementation of
a circular string scanned using external tables. This opcode will allow
direct modification and reading of values with the table opcodes.

  Syntax

aout scantable kamp, kpch, ipos, imass, istiff, idamp, ivel

  Initialization

ipos -- table containing position array.

imass -- table containing the mass of the string.

istiff -- table containing the stiffness of the string.

idamp -- table containing the damping factors of the string.

ivel -- table containing the velocities.

  Performance

kamp -- amplitude (gain) of the string.

kpch -- the string's scanned frequency.


===========================================================================
scanu                                                                 *scanu*

  Description

Compute the waveform and the wavetable for use in scanned synthesis.

  Syntax

scanu init, irate, ifnvel, ifnmass, ifnstif, ifncentr, ifndamp, kmass, \
      kstif, kcentr, kdamp, ileft, iright, kpos, kstrngth, ain, idisp, id

  Initialization

init -- the initial position of the masses. If this is a negative
number, then the absolute of init signifies the table to use as a hammer
shape. If init > 0, the length of it should be the same as the intended
mass number, otherwise it can be anything.

ifnvel -- the ftable that contains the initial velocity for each mass.
It should have the same size as the intended mass number.

ifnmass -- ftable that contains the mass of each mass. It should have
the same size as the intended mass number.

ifnstif -- ftable that contains the spring stiffness of each connection.
It should have the same size as the square of the intended mass number.
The data ordering is a row after row dump of the connection matrix of
the system.

ifncentr -- ftable that contains the centering force of each mass. It
should have the same size as the intended mass number.

ifndamp -- the ftable that contains the damping factor of each mass. It
should have the same size as the intended mass number.

ileft -- If init < 0, the position of the left hammer (ileft = 0 is hit
at leftmost, ileft = 1 is hit at rightmost).

iright -- If init < 0, the position of the right hammer (iright = 0 is
hit at leftmost, iright = 1 is hit at rightmost).

idisp -- If 0, no display of the masses is provided.

id -- If positive, the ID of the opcode. This will be used to point the
scanning opcode to the proper waveform maker. If this value is negative,
the absolute of this value is the wavetable on which to write the
waveshape. That wavetable can be used later from an other opcode to
generate sound. The initial contents of this table will be destroyed.

  Performance

kmass -- scales the masses

kstif -- scales the spring stiffness

kcentr -- scales the centering force

kdamp -- scales the damping

kpos -- position of an active hammer along the string (kpos = 0 is
leftmost, kpos = 1 is rightmost). The shape of the hammer is determined
by init and the power it pushes with is kstrngth.

kstrngth -- power that the active hammer uses

ain -- audio input that adds to the velocity of the masses. Amplitude
should not be too great.


===========================================================================
schedkwhen                                                       *schedkwhen*

  Description

Adds a new score event generated by a k-rate trigger.

  Syntax

schedkwhen ktrigger, kmintim, kmaxnum, kinsnum, kwhen, kdur \
      [, ip4] [, ip5] [...]

schedkwhen ktrigger, kmintim, kmaxnum, "insname", kwhen, kdur \
      [, ip4] [, ip5] [...]

  Initialization

“insname” -- A string (in double-quotes) representing a named instrument.

ip4, ip5, ... -- Equivalent to p4, p5, etc., in a score i statement

  Performance

ktrigger -- triggers a new score event. If ktrigger = 0, no new event is
triggered.

kmintim -- minimum time between generated events, in seconds. If kmintim
<= 0, no time limit exists. If the kinsnum is negative (to turn off an
instrument), this test is bypassed.

kmaxnum -- maximum number of simultaneous instances of instrument
kinsnum allowed. If the number of existant instances of kinsnum is >=
kmaxnum, no new event is generated. If kmaxnum is <= 0, it is not used
to limit event generation. If the kinsnum is negative (to turn off an
instrument), this test is bypassed.

kinsnum -- instrument number. Equivalent to p1 in a score i statement.

kwhen -- start time of the new event. Equivalent to p2 in a score i
statement. Measured from the time of the triggering event. kwhen must be
>= 0. If kwhen > 0, the instrument will not be initialized until the
actual time when it should start performing.

kdur -- duration of event. Equivalent to p3 in a score i statement. If
kdur = 0, the instrument will only do an initialization pass, with no
performance. If kdur is negative, a held note is initiated. (See ihold
and i statement.)

  Note

While waiting for events to be triggered by schedkwhen, the performance
must be kept going, or Csound may quit if no score events are expected.
To guarantee continued performance, an f0 statement may be used in the
score.

  Note

Note that the schedkwhen opcode can't accept string p-fields. If you
need to pass strings when instantiating an instrument, use the scoreline
or scoreline_i opcode.


===========================================================================
schedkwhennamed                                             *schedkwhennamed*

  Description

Similar to schedkwhen but uses a named instrument at init-time.

  Syntax

schedkwhennamed ktrigger, kmintim, kmaxnum, "name", kwhen, kdur \
      [, ip4] [, ip5] [...]

  Initialization

ip4, ip5, ... -- Equivalent to p4, p5, etc., in a score i statement

  Performance

ktrigger -- triggers a new score event. If ktrigger is 0, no new event
is triggered.

kmintim -- minimum time between generated events, in seconds. If kmintim
is less than or equal to 0, no time limit exists.

kmaxnum -- maximum number of simultaneous instances of named instrument
allowed. If the number of existant instances of the named instrument is
greater than or equal to kmaxnum, no new event is generated. If kmaxnum
is less than or equal to 0, it is not used to limit event generation.

"name" -- the named instrument's name.

kwhen -- start time of the new event. Equivalent to p2 in a score i
statement. Measured from the time of the triggering event. kwhen must be
greater than or equal to 0. If kwhen greater than 0, the instrument will
not be initialized until the actual time when it should start performing.

kdur -- duration of event. Equivalent to p3 in a score i statement. If
kdur is 0, the instrument will only do an initialization pass, with no
performance. If kdur is negative, a held note is initiated. (See ihold
and i statement.)

  Note

While waiting for events to be triggered by schedkwhennamed, the
performance must be kept going, or Csound may quit if no score events
are expected. To guarantee continued performance, an f0 statement may be
used in the score.

  Note

Note that the schedkwhennamed opcode can't accept string p-fields. If
you need to pass strings when instantiating an instrument, use the
scoreline or scoreline_i opcode.


===========================================================================
schedule                                                           *schedule*

  Description

Adds a new score event.

  Syntax

schedule insnum, iwhen, idur [, ip4] [, ip5] [...]

schedule "insname", iwhen, idur [, ip4] [, ip5] [...]

  Initialization

insnum -- instrument number. Equivalent to p1 in a score i statement.
insnum must be a number greater than the number of the calling instrument.

“insname” -- A string (in double-quotes) representing a named instrument.

iwhen -- start time of the new event. Equivalent to p2 in a score i
statement. iwhen must be nonnegative. If iwhen is zero, insum must be
greater than or equal to the p1 of the current instrument.

idur -- duration of event. Equivalent to p3 in a score i statement. .

ip4, ip5, ... -- Equivalent to p4, p5, etc., in a score i statement. The
opcode also accepts strings as arguments for p4-pN.

  Performance

schedule adds a new score event. The arguments, including options, are
the same as in a score. The iwhen time (p2) is measured from the time of
this event.

If the duration is zero or negative the new event is of MIDI type, and
inherits the release sub-event from the scheduling instruction.


===========================================================================
schedwhen                                                         *schedwhen*

  Description

Adds a new score event.

  Syntax

schedwhen ktrigger, kinsnum, kwhen, kdur [, ip4] [, ip5] [...]

schedwhen ktrigger, "insname", kwhen, kdur [, ip4] [, ip5] [...]

  Initialization

ip4, ip5, ... -- Equivalent to p4, p5, etc., in a score i statement.

  Performance

kinsnum -- instrument number. Equivalent to p1 in a score i statement.

“insname” -- A string (in double-quotes) representing a named instrument.

ktrigger -- trigger value for new event

kwhen -- start time of the new event. Equivalent to p2 in a score i
statement.

kdur -- duration of event. Equivalent to p3 in a score i statement.

schedwhen adds a new score event. The event is only scheduled when the
k-rate value ktrigger is first non-zero. The arguments, including
options, are the same as in a score. The kwhen time (p2) is measured
from the time of this event.

If the duration is zero or negative the new event is of MIDI type, and
inherits the release sub-event from the scheduling instruction.

  Note

Note that the schedwhen opcode can't accept string p-fields. If you need
to pass strings when instantiating an instrument, use the scoreline or
scoreline_i opcode.


===========================================================================
scoreline                                                         *scoreline*

  Description

Scoreline will issue one or more score events, if ktrig is 1 every
k-period. It can handle strings in the same conditions as the standard
score. Multi-line strings are accepted, using {{ }} to enclose the string.

  Syntax

scoreline Sin, ktrig

  Initialization

“Sin” -- a string (in double-quotes or enclosed by {{ }}) containing one
or more score events.

  Performance

“ktrig” -- event trigger, 1 issues the score event, 0 bypasses it.


===========================================================================
scoreline_i                                                     *scoreline_i*

  Description

scoreline_i will issue score events at i-time. It can handle strings in
the same conditions as the standard score. Multi-line strings are
accepted, using {{ }} to enclose the string.

  Syntax

scoreline_i Sin

  Initialization

“Sin” -- a string (in double-quotes or enclosed by {{ }}) containing one
or more score events.


===========================================================================
seed                                                                   *seed*

  Description

Sets the global seed value for all x-class noise generators, as well as
other opcodes that use a random call, such as grain.

  Please Note

rand, randh, randi, rnd(x) and birnd(x) are not affected by seed.

  Syntax

seed ival

  Performance

Use of seed will provide predictable results from an orchestra using
with random generators, when required from multiple performances.

When specifying a seed value, ival should be an integer between 0 and
2^32 . If ival = 0, the value of ival will be derived from the system
clock.


===========================================================================
sekere                                                               *sekere*

  Description

sekere is a semi-physical model of a sekere sound. It is one of the
PhISEM percussion opcodes. PhISEM (Physically Informed Stochastic Event
Modeling) is an algorithmic approach for simulating collisions of
multiple independent sound producing objects.

  Syntax

ares sekere iamp, idettack [, inum] [, idamp] [, imaxshake]

  Initialization

iamp -- Amplitude of output. Note: As these instruments are stochastic,
this is only a approximation.

idettack -- period of time over which all sound is stopped

inum (optional) -- The number of beads, teeth, bells, timbrels, etc. If
zero, the default value is 64.

idamp (optional) -- the damping factor, as part of this equation:

damping_amount = 0.998 + (idamp * 0.002)

The default damping_amount is 0.999 which means that the default value
of idamp is 0.5. The maximum damping_amount is 1.0 (no damping). This
means the maximum value for idamp is 1.0.

The recommended range for idamp is usually below 75% of the maximum value.

imaxshake (optional) -- amount of energy to add back into the system.
The value should be in range 0 to 1.


===========================================================================
semitone                                                           *semitone*

  Description

Calculates a factor to raise/lower a frequency by a given amount of
semitones.

  Syntax

semitone(x)

This function works at a-rate, i-rate, and k-rate.

  Initialization

x -- a value expressed in semitones.

  Performance

The value returned by the semitone function is a factor. You can
multiply a frequency by this factor to raise/lower it by the given
amount of semitones.


===========================================================================
sense                                                                 *sense*

  Description

Same as the sensekey opcode.

===========================================================================
sensekey                                                           *sensekey*

  Description

Returns the ASCII code of a key that has been pressed, or -1 if no key
has been pressed.

  Syntax

kres[, kkeydown] sensekey

  Performance

kres - returns the ASCII value of a key which is pressed or released.

kkeydown - returns 1 if the key was pressed, 0 if it was released or if
there is no key event.

kres can be used to read keyboard events from stdin and returns the
ASCII value of any key that is pressed or released, or it returns -1
when there is no keyboard activity. The value of kkeydown is 1 when a
key was pressed, or 0 otherwise. This behavior is emulated by default,
so a key release is generated immediately after every key press. To have
full functionality, FLTK can be used to capture keyboard events. FLpanel
can be used to capture keyboard events and send them to the sensekey
opcode, by adding an additional optional argument. See FLpanel for more
information.

  Note

This opcode can also be written as sense.


===========================================================================
serialBegin                                                     *serialBegin*

  Description

Open a serial port for arduino.

  Syntax

iPort serialBegin SPortName [, ibaudRate]

  Initialization

SPortName -- port name number

ibaudrate -- serial speed, defaulting to 9600 bps.


===========================================================================
serialEnd                                                         *serialEnd*

  Description

Close a serial port for arduino.

  Syntax

 serialEnd iPort

  Initialization

iPort -- port number optained from a serialBeginopcode.


===========================================================================
serialFlush                                                     *serialFlush*

  Description

Flush to the screen any bytes (up to 32k) in the input buffer. Note that
these bytes will be cleared from the buffer. use this opcode mainly for
debugging messages. If you want to mix debugging and other communication
messages over the same port, you will need to manually parse the data
with the serialRead opcode.

  Syntax

 serialFlush iPort

  Performance

iPort -- port number optained from a serialBegin opcode.


===========================================================================
serialPrint                                                     *serialPrint*

  Description

Print to the screen any bytes (up to 32k) in the input buffer. Note that
these bytes will be cleared from the buffer. use this opcode mainly for
debugging messages. If you want to mix debugging and other communication
messages over the same port, you will need to manually parse the data
with the serialRead opcode.

  Syntax

 serialPrint iPort

  Performance

iPort -- port number optained from a serialBegin opcode.


===========================================================================
serialRead                                                       *serialRead*

  Description

Read data from a serial port for arduino.

  Syntax

kByte serialRead iPort

  Performance

iPort -- port number optained from a serialBegin opcode.

kByte -- a byte of data to read.


===========================================================================
serialWrite_i                                                 *serialWrite_i*

  Description

Write data to a serial port for arduino.

  Syntax

 serialWrite_i iPort, iByte

 serialWrite_i iPort, SBytes

  Initialization

iPort -- port number optained from a serialBegin opcode.

iByte -- a byte of data to write.


===========================================================================
serialWrite                                                     *serialWrite*

  Description

Write data to a serial port for arduino.

  Syntax

 serialWrite iPort, iByte

 serialWrite iPort, kByte

 serialWrite iPort, SBytes

  Performance

iPort -- port number optained from a serialBegin opcode.

iByte -- a byte of data to write.


===========================================================================
seqtime2                                                           *seqtime2*

  Description

Generates a trigger signal according to the values stored in a table.

  Syntax

ktrig_out seqtime2 ktrig_in, ktime_unit, kstart, kloop, kinitndx, kfn_times

  Performance

ktrig_out -- output trigger signal

ktime_unit -- unit of measure of time, related to seconds.

ktrig_in -- input trigger signal.

kstart -- start index of looped section

kloop -- end index of looped section

kinitndx -- initial index

  Note

Although kinitndx is listed as k-rate, it is in fact accessed only at
init-time. So if you are using a k-rate argument, it must be assigned
with init.

kfn_times -- number of table containing a sequence of times

This opcode handles timed-sequences of groups of values stored into a
table.

seqtime2 generates a trigger signal (a sequence of impulses, see also
trigger opcode), according to the values stored in the kfn_times table.
This table should contain a series of delta-times (i.e. times beetween
to adjacent events). The time units stored into table are expressed in
seconds, but can be rescaled by means of ktime_unit argument. The table
can be filled with GEN02 or by means of an external text-file containing
numbers, with GEN23.

It is possible to start the sequence from a value different than the
first, by assigning to initndx an index different than zero (which
corresponds to the first value of the table). Normally the sequence is
looped, and the start and end of loop can be adjusted by modifying
kstart and kloop arguments. User must be sure that values of these
arguments (as well as initndx) correspond to valid table numbers,
otherwise Csound will crash (because no range-checking is implementeted).

It is possible to disable loop (one-shot mode) by assigning the same
value both to kstart and kloop arguments. In this case, the last read
element will be the one corresponding to the value of such arguments.
Table can be read backward by assigning a negative kloop value. It is
possible to trigger two events almost at the same time (actually
separated by a k-cycle) by giving a zero value to the corresponding
delta-time. First element contained in the table should be zero, if the
user intends to send a trigger impulse, it should come immediately after
the orchestra instrument containing seqtime2 opcode.

seqtime2 is similar to seqtime, the difference is that when ktrig_in
contains a non-zero value, current index is reset to kinitndx value.
kinitndx can be varied at performance time.


===========================================================================
seqtime                                                             *seqtime*

  Description

Generates a trigger signal according to the values stored in a table.

  Syntax

ktrig_out seqtime ktime_unit, kstart, kloop, kinitndx, kfn_times

  Performance

ktrig_out -- output trigger signal

ktime_unit -- unit of measure of time, related to seconds.

kstart -- start index of looped section

kloop -- end index of looped section

kinitndx -- initial index

  Note

Although kinitndx is listed as k-rate, it is in fact accessed only at
init-time. So if you are using a k-rate argument, it must be assigned
with init.

kfn_times -- number of table containing a sequence of times

This opcode handles timed-sequences of groups of values stored into a
table.

seqtime generates a trigger signal (a sequence of impulses, see also
trigger opcode), according to the values stored in the kfn_times table.
This table should contain a series of delta-times (i.e. times beetween
to adjacent events). The time units stored into table are expressed in
seconds, but can be rescaled by means of ktime_unit argument. The table
can be filled with GEN02 or by means of an external text-file containing
numbers, with GEN23.

  Note

Note that the kloop index marks the loop boundary and is NOT included in
the looped elements. If you want to loop the first four elements, you
would set kstart to 0 and kloop to 4.

It is possible to start the sequence from a value different than the
first, by assigning to kinitndx an index different than zero (which
corresponds to the first value of the table). Normally the sequence is
looped, and the start and end of loop can be adjusted by modifying
kstart and kloop arguments. User must be sure that values of these
arguments (as well as kinitndx) correspond to valid table numbers,
otherwise Csound will crash (because no range-checking is implementeted).

It is possible to disable loop (one-shot mode) by assigning the same
value both to kstart and kloop arguments. In this case, the last read
element will be the one corresponding to the value of such arguments.
Table can be read backward by assigning a negative kloop value. It is
possible to trigger two events almost at the same time (actually
separated by a k-cycle) by giving a zero value to the corresponding
delta-time. First element contained in the table should be zero, if the
user intends to send a trigger impulse, it should come immediately after
the orchestra instrument containing seqtime opcode.


===========================================================================
setctrl                                                             *setctrl*

  Description

Configurable slider controls for realtime user input. Requires Winsound
or TCL/TK. setctrl sets a slider to a specific value, or sets a minimum
or maximum range.

  Syntax

setctrl inum, ival, itype

  Initialization

Note that this opcode is not available on Windows due to the
implimentation of pipes on that system

inum -- number of the slider to set

ival -- value to be sent to the slider

itype -- type of value sent to the slider as follows:

  * 1 -- set the current value. Initial value is 0.

  * 2 -- set the minimum value. Default is 0.

  * 3 -- set the maximum value. Default is 127.

  * 4 -- set the label. (New in Csound version 4.09)

  Performance

Calling setctrl will create a new slider on the screen. There is no
theoretical limit to the number of sliders. Windows and TCL/TK use only
integers for slider values, so the values may need rescaling. GUIs
usually pass values at a fairly slow rate, so it may be advisable to
pass the output of control through port.


===========================================================================
setksmps                                                           *setksmps*

  Description

Sets the local ksmps value in an instrument or user-defined opcode block.

  Syntax

setksmps iksmps

  Initialization

iksmps -- sets the local ksmps value.

If iksmps is set to zero, the ksmps of the caller instrument or opcode
is used (this is the default behavior).

  Note

The local ksmps is implemented by splitting up a control period into
smaller sub-kperiods and setting up the instrument local ksmps to the
new value. This also requires converting the rate of k-rate input and
output arguments (input variables receive the same value in all
sub-kperiods, while outputs are written only in the last one). It also
means that you cannot use a local ksmps that is higher than the global
ksmps.

  Warning about local ksmps

When the local ksmps is not the same as the orchestra level ksmps value
(as specified in the orchestra header), global a-rate operations must be
carefully coded to access the data in a vector according to the local
ksmps. The audio rate bus channel opcodes (chnget/chnset) can be used
freely, however, as they will do the necessary conversion between ksmp
sizes.

Other opcodes that require some care include:

  * any access to “ga” variables

  * a-rate zak opcodes (zar, zaw, etc.)

  * tablera and tablewa (these two opcodes may in fact work, but caution
    is needed)

  * The in and out opcode family cannot be used in local-ksmps UDOs
    (these read from, and write to global a-rate buffers), but are safe
    in local-ksmps instruments

In general, the local ksmps should be used with care as it is an
experimental feature. Though it works correctly in most cases.

The setksmps statement can be used to set the local ksmps value of the
instrument or user-defined opcode block. It has one i-time parameter
specifying the new ksmps value (which is left unchanged if zero is
used). setksmps should be used before any other opcodes (but allowed
after xin in UDOs), otherwise unpredictable results may occur.

  Performance

The syntax of a user-defined opcode block is as follows:

opcode  name, outtypes, intypes
xinarg1 [, xinarg2] [, xinarg3] ... [xinargN]  xin
[setksmps  iksmps]
... the rest of the instrument's code.
xout  xoutarg1 [, xoutarg2] [, xoutarg3] ... [xoutargN]
endop

The new opcode can then be used with the usual syntax:

[xinarg1] [, xinarg2] ... [xinargN]  name  [xoutarg1] [, xoutarg2] ... [xoutargN] [, iksmps]


===========================================================================
setrow                                                               *setrow*

  Description

Sets a given row of a 2-dimensional array. The output is an 2-d array
with the contents of the requested row set to values of the input array
(1-d; if 2-d the first row of the input array is used).

  Syntax

kout[] setrowkin[],krow

  Performance

kout[] -- output array containing the set row. It will be created if it
does not exist.

kin[] -- input array.

krow -- row to be set.


===========================================================================
setscorepos                                                     *setscorepos*

  Description

Sets the playback position of the current score performance to a given
position.

  Syntax

 setscorepos ipos

  Initialization

ipos -- playback position in seconds.


===========================================================================
sfilist                                                             *sfilist*

  Description

Prints a list of all instruments of a previously loaded SoundFont2 (SF2)
sample file. These opcodes allow management the sample-structure of SF2
files. In order to understand the usage of these opcodes, the user must
have some knowledge of the SF2 format, so a brief description of this
format can be found in the SoundFont2 File Format Appendix.

  Syntax

sfilist ifilhandle

  Initialization

ifilhandle -- unique number generated by sfload opcode to be used as an
identifier for a SF2 file. Several SF2 files can be loaded and activated
at the same time.

  Performance

sfilist prints a list of all instruments of a previously loaded SF2 file
to the console.

These opcodes only support the sample structure of SF2 files. The
modulator structure of the SoundFont2 format is not supported in Csound.
Any modulation or processing to the sample data is left to the Csound
user, bypassing all restrictions forced by the SF2 standard.


===========================================================================
sfinstr3                                                           *sfinstr3*

  Description

Plays a SoundFont2 (SF2) sample instrument, generating a stereo sound
with cubic interpolation. These opcodes allow management the
sample-structure of SF2 files. In order to understand the usage of these
opcodes, the user must have some knowledge of the SF2 format, so a brief
description of this format can be found in the SoundFont2 File Format
Appendix.

  Syntax

ar1, ar2 sfinstr3 ivel, inotenum, xamp, xfreq, instrnum, ifilhandle \
      [, iflag] [, ioffset]

  Initialization

ivel -- velocity value

inotenum -- MIDI note number value

instrnum -- number of an instrument of a SF2 file.

ifilhandle -- unique number generated by sfload opcode to be used as an
identifier for a SF2 file. Several SF2 files can be loaded and activated
at the same time.

iflag (optional) -- flag regarding the behavior of xfreq and inotenum

ioffset (optional) -- start playing at offset, in samples.

  Performance

xamp -- amplitude correction factor

xfreq -- frequency value or frequency multiplier, depending by iflag.
When iflag = 0, xfreq is a multiplier of a the default frequency,
assigned by SF2 preset to the inotenum value. When iflag = 1, xfreq is
the absolute frequency of the output sound, in Hz. Default is 0.

When iflag = 0, inotenum sets the frequency of the output according to
the MIDI note number used, and xfreq is used as a multiplier. When iflag
= 1, the frequency of the output, is set directly by xfreq. This allows
the user to use any kind of micro-tuning based scales. However, this
method is designed to work correctly only with presets tuned to the
default equal temperament. Attempts to use this method with a preset
already having non-standard tunings, or with drum-kit-based presets,
could give unexpected results.

Adjustment of the amplitude can be done by varying the xamp argument,
which acts as a multiplier.

The ioffset parameter allows the sound to start from a sample different
than the first one. The user should make sure that its value is within
the length of the specific sound. Otherwise, Csound will probably crash.

sfinstr3 is a cubic-interpolation version of sfinstr. Difference of
sound-quality is noticeable specially in bass-frequency-transposed
samples. In high-freq-transposed samples the difference is less
noticeable, and I suggest to use linear-interpolation versions, because
they are faster.

These opcodes only support the sample structure of SF2 files. The
modulator structure of the SoundFont2 format is not supported in Csound.
Any modulation or processing to the sample data is left to the Csound
user, bypassing all restrictions forced by the SF2 standard.


===========================================================================
sfinstr3m                                                         *sfinstr3m*

  Description

Plays a SoundFont2 (SF2) sample instrument, generating a mono sound with
cubic interpolation. These opcodes allow management the sample-structure
of SF2 files. In order to understand the usage of these opcodes, the
user must have some knowledge of the SF2 format, so a brief description
of this format can be found in the SoundFont2 File Format Appendix.

  Syntax

ares sfinstr3m ivel, inotenum, xamp, xfreq, instrnum, ifilhandle \
      [, iflag] [, ioffset]

  Initialization

ivel -- velocity value

inotenum -- MIDI note number value

instrnum -- number of an instrument of a SF2 file.

ifilhandle -- unique number generated by sfload opcode to be used as an
identifier for a SF2 file. Several SF2 files can be loaded and activated
at the same time.

iflag (optional) -- flag regarding the behavior of xfreq and inotenum

ioffset (optional) -- start playing at offset, in samples.

  Performance

xamp -- amplitude correction factor

xfreq -- frequency value or frequency multiplier, depending by iflag.
When iflag = 0, xfreq is a multiplier of a the default frequency,
assigned by SF2 preset to the inotenum value. When iflag = 1, xfreq is
the absolute frequency of the output sound, in Hz. Default is 0.

When iflag = 0, inotenum sets the frequency of the output according to
the MIDI note number used, and xfreq is used as a multiplier. When iflag
= 1, the frequency of the output, is set directly by xfreq. This allows
the user to use any kind of micro-tuning based scales. However, this
method is designed to work correctly only with presets tuned to the
default equal temperament. Attempts to use this method with a preset
already having non-standard tunings, or with drum-kit-based presets,
could give unexpected results.

Adjustment of the amplitude can be done by varying the xamp argument,
which acts as a multiplier.

The ioffset parameter allows the sound to start from a sample different
than the first one. The user should make sure that its value is within
the length of the specific sound. Otherwise, Csound will probably crash.

sfinstr3m is a cubic-interpolation version of sfinstrm. Difference of
sound-quality is noticeable specially in bass-frequency-transposed
samples. In high-freq-transposed samples the difference is less
noticeable, and I suggest to use linear-interpolation versions, because
they are faster.

These opcodes only support the sample structure of SF2 files. The
modulator structure of the SoundFont2 format is not supported in Csound.
Any modulation or processing to the sample data is left to the Csound
user, bypassing all restrictions forced by the SF2 standard.


===========================================================================
sfinstr                                                             *sfinstr*

  Description

Plays a SoundFont2 (SF2) sample instrument, generating a stereo sound.
These opcodes allow management the sample-structure of SF2 files. In
order to understand the usage of these opcodes, the user must have some
knowledge of the SF2 format, so a brief description of this format can
be found in the SoundFont2 File Format Appendix.

  Syntax

ar1, ar2 sfinstr ivel, inotenum, xamp, xfreq, instrnum, ifilhandle \
      [, iflag] [, ioffset]

  Initialization

ivel -- velocity value

inotenum -- MIDI note number value

instrnum -- number of an instrument of a SF2 file.

ifilhandle -- unique number generated by sfload opcode to be used as an
identifier for a SF2 file. Several SF2 files can be loaded and activated
at the same time.

iflag (optional) -- flag regarding the behavior of xfreq and inotenum

ioffset (optional) -- start playing at offset, in samples.

  Performance

xamp -- amplitude correction factor

xfreq -- frequency value or frequency multiplier, depending by iflag.
When iflag = 0, xfreq is a multiplier of a the default frequency,
assigned by SF2 preset to the inotenum value. When iflag = 1, xfreq is
the absolute frequency of the output sound, in Hz. Default is 0.

When iflag = 0, inotenum sets the frequency of the output according to
the MIDI note number used, and xfreq is used as a multiplier. When iflag
= 1, the frequency of the output, is set directly by xfreq. This allows
the user to use any kind of micro-tuning based scales. However, this
method is designed to work correctly only with presets tuned to the
default equal temperament. Attempts to use this method with a preset
already having non-standard tunings, or with drum-kit-based presets,
could give unexpected results.

Adjustment of the amplitude can be done by varying the xamp argument,
which acts as a multiplier.

The ioffset parameter allows the sound to start from a sample different
than the first one. The user should make sure that its value is within
the length of the specific sound. Otherwise, Csound will probably crash.

sfinstr plays an SF2 instrument instead of a preset (an SF2 instrument
is the base of a preset layer). instrnum specifies the instrument
number, and the user must be sure that the specified number belongs to
an existing instrument of a determinate soundfont bank. Notice that both
xamp and xfreq can operate at k-rate as well as a-rate, but both
arguments must work at the same rate.

These opcodes only support the sample structure of SF2 files. The
modulator structure of the SoundFont2 format is not supported in Csound.
Any modulation or processing to the sample data is left to the Csound
user, bypassing all restrictions forced by the SF2 standard.


===========================================================================
sfinstrm                                                           *sfinstrm*

  Description

Plays a SoundFont2 (SF2) sample instrument, generating a mono sound.
These opcodes allow management the sample-structure of SF2 files. In
order to understand the usage of these opcodes, the user must have some
knowledge of the SF2 format, so a brief description of this format can
be found in the SoundFont2 File Format Appendix.

  Syntax

ares sfinstrm ivel, inotenum, xamp, xfreq, instrnum, ifilhandle \
      [, iflag] [, ioffset]

  Initialization

ivel -- velocity value

inotenum -- MIDI note number value

instrnum -- number of an instrument of a SF2 file.

ifilhandle -- unique number generated by sfload opcode to be used as an
identifier for a SF2 file. Several SF2 files can be loaded and activated
at the same time.

iflag (optional) -- flag regarding the behavior of xfreq and inotenum

ioffset (optional) -- start playing at offset, in samples.

  Performance

xamp -- amplitude correction factor

xfreq -- frequency value or frequency multiplier, depending by iflag.
When iflag = 0, xfreq is a multiplier of a the default frequency,
assigned by SF2 preset to the inotenum value. When iflag = 1, xfreq is
the absolute frequency of the output sound, in Hz. Default is 0.

When iflag = 0, inotenum sets the frequency of the output according to
the MIDI note number used, and xfreq is used as a multiplier. When iflag
= 1, the frequency of the output, is set directly by xfreq. This allows
the user to use any kind of micro-tuning based scales. However, this
method is designed to work correctly only with presets tuned to the
default equal temperament. Attempts to use this method with a preset
already having non-standard tunings, or with drum-kit-based presets,
could give unexpected results.

Adjustment of the amplitude can be done by varying the xamp argument,
which acts as a multiplier.

The ioffset parameter allows the sound to start from a sample different
than the first one. The user should make sure that its value is within
the length of the specific sound. Otherwise, Csound will probably crash.

sfinstrm is a mono version of sfinstr. This is the fastest opcode of the
SF2 family.

These opcodes only support the sample structure of SF2 files. The
modulator structure of the SoundFont2 format is not supported in Csound.
Any modulation or processing to the sample data is left to the Csound
user, bypassing all restrictions forced by the SF2 standard.


===========================================================================
sfload                                                               *sfload*

  Description

Loads an entire SoundFont2 (SF2) sample file into memory. These opcodes
allow management the sample-structure of SF2 files. In order to
understand the usage of these opcodes, the user must have some knowledge
of the SF2 format, so a brief description of this format can be found in
the SoundFont2 File Format Appendix.

sfload should be placed in the header section of a Csound orchestra.

  Syntax

ir sfload "filename"

  Initialization

ir -- output to be used by other SF2 opcodes. For sfload, ir is ifilhandle.

“filename” -- name of the SF2 file, with its complete path. It must be a
string typed within double-quotes with “/” to separate directories (this
applies to DOS and Windows as well, where using a backslash will
generate an error), or an integer that has been the subject of a strset
operation

  Performance

sfload loads an entire SF2 file into memory. It returns a file handle to
be used by other opcodes. Several instances of sfload can placed in the
header section of an orchestra, allowing use of more than one SF2 file
in a single orchestra.

These opcodes only support the sample structure of SF2 files. The
modulator structure of the SoundFont2 format is not supported in Csound.
Any modulation or processing to the sample data is left to the Csound
user, bypassing all restrictions forced by the SF2 standard.

It should be noted that before version 5.12 a maximum of 10 sound fonts
could be loaded, a restriction since relaxed.


===========================================================================
sflooper                                                           *sflooper*

  Description

Plays a SoundFont2 (SF2) sample preset, generating a stereo sound,
similarly to sfplay. Unlike that opcode, though, it ignores the looping
points set in the SF2 file and substitutes them for a user-defined
crossfade loop. It is a cross between sfplay and flooper2.

  Syntax

ar1, ar2 sflooper ivel, inotenum, kamp, kpitch, ipreindex, kloopstart, kloopend, kcrossfade \
      [, istart, imode, ifenv, iskip] 

  Initialization

ivel -- velocity value

inotenum -- MIDI note number value

ipreindex -- preset index

istart -- playback start pos in seconds

imode -- loop modes: 0 forward, 1 backward, 2 back-and-forth [def: 0]

ifenv -- if non-zero, crossfade envelope shape table number. The
default, 0, sets the crossfade to linear.

iskip -- if 1, the opcode initialisation is skipped, for tied notes,
performance continues from the position in the loop where the previous
note stopped. The default, 0, does not skip initialisation

  Performance

kamp -- amplitude scaling

kpitch -- pitch control (transposition ratio); negative values are not
allowed.

kloopstart -- loop start point (secs). Note that although k-rate, loop
parameters such as this are only updated once per loop cycle. If loop
start is set beyond the end of the sample, no looping will result.

kloopend -- loop end point (secs), updated once per loop cycle.

kcrossfade -- crossfade length (secs), updated once per loop cycle and
limited to loop length.

sflooper plays a preset, generating a stereo sound.

These opcodes only support the sample structure of SF2 files. The
modulator structure of the SoundFont2 format is not supported in Csound.
Any modulation or processing to the sample data is left to the Csound
user, bypassing all restrictions forced by the SF2 standard.

Note: The looping points are set on the root key of every sample that is
part of the preset of the soundfont. For instance, a soundfont can have
a single sample for the whole keyboard. In that case, sflooper will work
like flooper and flooper2, because as the sample is transposed, played
back at different rates, the loop will get short or longer. If however
the soundfont has a sample for each key, than there will be no
transposition and the loop will stay the same length (unless you change
kpitch).


===========================================================================
sfpassign                                                         *sfpassign*

  Description

Assigns all presets of a previously loaded SoundFont2 (SF2) sample file
to a sequence of progressive index numbers. These opcodes allow
management the sample-structure of SF2 files. In order to understand the
usage of these opcodes, the user must have some knowledge of the SF2
format, so a brief description of this format can be found in the
SoundFont2 File Format Appendix.

sfpassign should be placed in the header section of a Csound orchestra.

  Syntax

sfpassign istartindex, ifilhandle[, imsgs]

  Initialization

istartindex -- starting index preset by the user in bulk preset
assignments.

ifilhandle -- unique number generated by sfload opcode to be used as an
identifier for a SF2 file. Several SF2 files can be loaded and activated
at the same time.

imsgs -- if non-zero messages are suppressed.

  Performance

sfpassign assigns all presets of a previously loaded SF2 file to a
sequence of progressive index numbers, to be used later with the opcodes
sfplay and sfplaym. istartindex specifies the starting index number. Any
number of sfpassign instances can be placed in the header section of an
orchestra, each one assigning presets belonging to different SF2 files.
The user must take care that preset index numbers of different SF2 files
do not overlap.

These opcodes only support the sample structure of SF2 files. The
modulator structure of the SoundFont2 format is not supported in Csound.
Any modulation or processing to the sample data is left to the Csound
user, bypassing all restrictions forced by the SF2 standard.


===========================================================================
sfplay3                                                             *sfplay3*

  Description

Plays a SoundFont2 (SF2) sample preset, generating a stereo sound with
cubic interpolation. These opcodes allow management the sample-structure
of SF2 files. In order to understand the usage of these opcodes, the
user must have some knowledge of the SF2 format, so a brief description
of this format can be found in the SoundFont2 File Format Appendix.

  Syntax

ar1, ar2 sfplay3 ivel, inotenum, xamp, xfreq, ipreindex [, iflag] [, ioffset] [, ienv]

  Initialization

ivel -- velocity value

inotenum -- MIDI note number value

ipreindex -- preset index

iflag (optional) -- flag regarding the behavior of xfreq and inotenum

ioffset (optional) -- start playing at offset, in samples.

ienv (optional) -- enables and determines amplitude envelope. 0 = no
envelope, 1 = linear attack and decay, 2 = linear attack, exponential
decay (see below). Default = 0.

  Performance

xamp -- amplitude correction factor

xfreq -- frequency value or frequency multiplier, depending by iflag.
When iflag = 0, xfreq is a multiplier of a the default frequency,
assigned by SF2 preset to the inotenum value. When iflag = 1, xfreq is
the absolute frequency of the output sound, in Hz. Default is 0.

When iflag = 0, inotenum sets the frequency of the output according to
the MIDI note number used, and xfreq is used as a multiplier. When iflag
= 1, the frequency of the output, is set directly by xfreq. This allows
the user to use any kind of micro-tuning based scales. However, this
method is designed to work correctly only with presets tuned to the
default equal temperament. Attempts to use this method with a preset
already having non-standard tunings, or with drum-kit-based presets,
could give unexpected results.

Adjustment of the amplitude can be done by varying the xamp argument,
which acts as a multiplier.

Notice that both xamp and xfreq can use k-rate as well as a-rate
signals. Both arguments must use variables of the same rate, or sfplay3
will not work correctly. ipreindex must contain the number of a
previously assigned preset, or Csound will crash.

The ioffset parameter allows the sound to start from a sample different
than the first one. The user should make sure that its value is within
the length of the specific sound. Otherwise, Csound will probably crash.

The ienv parameter enables and determines the type of amplitude envelope
used. The default value is 0, or no envelope. If ienv is set to 1, the
attack and decay portions are linear. If set to 2, the attack is linear
and the decay is exponential. The release portion of the envelope has
not yet been implemented.

sfplay3 plays a preset, generating a stereo sound with cubic
interpolation. ivel does not directly affect the amplitude of the
output, but informs sfplay3 about which sample should be chosen in
multi-sample, velocity-split presets.

sfplay3 is a cubic-interpolation version of sfplay. Difference of
sound-quality is noticeable specially in bass-frequency-transposed
samples. In high-freq-transposed samples the difference is less
noticeable, and I suggest to use linear-interpolation versions, because
they are faster.

These opcodes only support the sample structure of SF2 files. The
modulator structure of the SoundFont2 format is not supported in Csound.
Any modulation or processing to the sample data is left to the Csound
user, bypassing all restrictions forced by the SF2 standard.


===========================================================================
sfplay3m                                                           *sfplay3m*

  Description

Plays a SoundFont2 (SF2) sample preset, generating a mono sound with
cubic interpolation. These opcodes allow management the sample-structure
of SF2 files. In order to understand the usage of these opcodes, the
user must have some knowledge of the SF2 format, so a brief description
of this format can be found in the SoundFont2 File Format Appendix.

  Syntax

ares sfplay3m ivel, inotenum, xamp, xfreq, ipreindex [, iflag] [, ioffset] [, ienv]

  Initialization

ivel -- velocity value

inotenum -- MIDI note number value

ipreindex -- preset index

iflag (optional) -- flag regarding the behavior of xfreq and inotenum

ioffset (optional) -- start playing at offset, in samples.

ienv (optional) -- enables and determines amplitude envelope. 0 = no
envelope, 1 = linear attack and decay, 2 = linear attack, exponential
decay (see below). Default = 0.

  Performance

xamp -- amplitude correction factor

xfreq -- frequency value or frequency multiplier, depending by iflag.
When iflag = 0, xfreq is a multiplier of a the default frequency,
assigned by SF2 preset to the inotenum value. When iflag = 1, xfreq is
the absolute frequency of the output sound, in Hz. Default is 0.

When iflag = 0, inotenum sets the frequency of the output according to
the MIDI note number used, and xfreq is used as a multiplier. When iflag
= 1, the frequency of the output, is set directly by xfreq. This allows
the user to use any kind of micro-tuning based scales. However, this
method is designed to work correctly only with presets tuned to the
default equal temperament. Attempts to use this method with a preset
already having non-standard tunings, or with drum-kit-based presets,
could give unexpected results.

Adjustment of the amplitude can be done by varying the xamp argument,
which acts as a multiplier.

Notice that both xamp and xfreq can use k-rate as well as a-rate
signals. Both arguments must use variables of the same rate, or sfplay3m
will not work correctly. ipreindex must contain the number of a
previously assigned preset, or Csound will crash.

The ioffset parameter allows the sound to start from a sample different
than the first one. The user should make sure that its value is within
the length of the specific sound. Otherwise, Csound will probably crash.

The ienv parameter enables and determines the type of amplitude envelope
used. The default value is 0, or no envelope. If ienv is set to 1, the
attack and decay portions are linear. If set to 2, the attack is linear
and the decay is exponential. The release portion of the envelope has
not yet been implemented.

sfplay3m is a mono version of sfplay3. It should be used with mono
preset, or with the stereo presets in which stereo output is not
required. It is faster than sfplay3.

sfplay3m is also a cubic-interpolation version of sfplaym. Difference of
sound-quality is noticeable specially in bass-frequency-transposed
samples. In high-freq-transposed samples the difference is less
noticeable, and I suggest to use linear-interpolation versions, because
they are faster.

These opcodes only support the sample structure of SF2 files. The
modulator structure of the SoundFont2 format is not supported in Csound.
Any modulation or processing to the sample data is left to the Csound
user, bypassing all restrictions forced by the SF2 standard.


===========================================================================
sfplay                                                               *sfplay*

  Description

Plays a SoundFont2 (SF2) sample preset, generating a stereo sound. These
opcodes allow management the sample-structure of SF2 files. In order to
understand the usage of these opcodes, the user must have some knowledge
of the SF2 format, so a brief description of this format can be found in
the SoundFont2 File Format Appendix.

  Syntax

ar1, ar2 sfplay ivel, inotenum, xamp, xfreq, ipreindex [, iflag] [, ioffset] [, ienv]

  Initialization

ivel -- velocity value

inotenum -- MIDI note number value

ipreindex -- preset index

iflag (optional) -- flag regarding the behavior of xfreq and inotenum

ioffset (optional) -- start playing at offset, in samples.

ienv (optional) -- enables and determines amplitude envelope. 0 = no
envelope, 1 = linear attack and decay, 2 = linear attack, exponential
decay (see below). Default = 0.

  Performance

xamp -- amplitude correction factor

xfreq -- frequency value or frequency multiplier, depending by iflag.
When iflag = 0, xfreq is a multiplier of a the default frequency,
assigned by SF2 preset to the inotenum value. When iflag = 1, xfreq is
the absolute frequency of the output sound, in Hz. Default is 0.

When iflag = 0, inotenum sets the frequency of the output according to
the MIDI note number used, and xfreq is used as a multiplier. When iflag
= 1, the frequency of the output, is set directly by xfreq. This allows
the user to use any kind of micro-tuning based scales. However, this
method is designed to work correctly only with presets tuned to the
default equal temperament. Attempts to use this method with a preset
already having non-standard tunings, or with drum-kit-based presets,
could give unexpected results.

Adjustment of the amplitude can be done by varying the xamp argument,
which acts as a multiplier.

Notice that both xamp and xfreq can use k-rate as well as a-rate
signals. Both arguments must use variables of the same rate, or sfplay
will not work correctly. ipreindex must contain the number of a
previously assigned preset, or Csound will crash.

The ioffset parameter allows the sound to start from a sample different
than the first one. The user should make sure that its value is within
the length of the specific sound. Otherwise, Csound will probably crash.

The ienv parameter enables and determines the type of amplitude envelope
used. The default value is 0, or no envelope. If ienv is set to 1, the
attack and decay portions are linear. If set to 2, the attack is linear
and the decay is exponential. The release portion of the envelope has
not yet been implemented.

sfplay plays a preset, generating a stereo sound. ivel does not directly
affect the amplitude of the output, but informs sfplay about which
sample should be chosen in multi-sample, velocity-split presets.

These opcodes only support the sample structure of SF2 files. The
modulator structure of the SoundFont2 format is not supported in Csound.
Any modulation or processing to the sample data is left to the Csound
user, bypassing all restrictions forced by the SF2 standard.


===========================================================================
sfplaym                                                             *sfplaym*

  Description

Plays a SoundFont2 (SF2) sample preset, generating a mono sound. These
opcodes allow management the sample-structure of SF2 files. In order to
understand the usage of these opcodes, the user must have some knowledge
of the SF2 format, so a brief description of this format can be found in
the SoundFont2 File Format Appendix.

  Syntax

ares sfplaym ivel, inotenum, xamp, xfreq, ipreindex [, iflag] [, ioffset] [, ienv]

  Initialization

ivel -- velocity value

inotenum -- MIDI note number value

ipreindex -- preset index

iflag (optional) -- flag regarding the behavior of xfreq and inotenum

ioffset (optional) -- start playing at offset, in samples.

ienv (optional) -- enables and determines amplitude envelope. 0 = no
envelope, 1 = linear attack and decay, 2 = linear attack, exponential
decay (see below). Default = 0.

  Performance

xamp -- amplitude correction factor

xfreq -- frequency value or frequency multiplier, depending by iflag.
When iflag = 0, xfreq is a multiplier of a the default frequency,
assigned by SF2 preset to the inotenum value. When iflag = 1, xfreq is
the absolute frequency of the output sound, in Hz. Default is 0.

When iflag = 0, inotenum sets the frequency of the output according to
the MIDI note number used, and xfreq is used as a multiplier. When iflag
= 1, the frequency of the output, is set directly by xfreq. This allows
the user to use any kind of micro-tuning based scales. However, this
method is designed to work correctly only with presets tuned to the
default equal temperament. Attempts to use this method with a preset
already having non-standard tunings, or with drum-kit-based presets,
could give unexpected results.

Adjustment of the amplitude can be done by varying the xamp argument,
which acts as a multiplier.

Notice that both xamp and xfreq can use k-rate as well as a-rate
signals. Both arguments must use variables of the same rate, or sfplay
will not work correctly. ipreindex must contain the number of a
previously assigned preset, or Csound will crash.

The ioffset parameter allows the sound to start from a sample different
than the first one. The user should make sure that its value is within
the length of the specific sound. Otherwise, Csound will probably crash.

The ienv parameter enables and determines the type of amplitude envelope
used. The default value is 0, or no envelope. If ienv is set to 1, the
attack and decay portions are linear. If set to 2, the attack is linear
and the decay is exponential. The release portion of the envelope has
not yet been implemented.

sfplaym is a mono version of sfplay. It should be used with mono preset,
or with the stereo presets in which stereo output is not required. It is
faster than sfplay.

These opcodes only support the sample structure of SF2 files. The
modulator structure of the SoundFont2 format is not supported in Csound.
Any modulation or processing to the sample data is left to the Csound
user, bypassing all restrictions forced by the SF2 standard.


===========================================================================
sfplist                                                             *sfplist*

  Description

Prints a list of all presets of a previously loaded SoundFont2 (SF2)
sample file. These opcodes allow management the sample-structure of SF2
files. In order to understand the usage of these opcodes, the user must
have some knowledge of the SF2 format, so a brief description of this
format can be found in the SoundFont2 File Format Appendix.

  Syntax

sfplist ifilhandle

  Initialization

ifilhandle -- unique number generated by sfload opcode to be used as an
identifier for a SF2 file. Several SF2 files can be loaded and activated
at the same time.

  Performance

sfplist prints a list of all presets of a previously loaded SF2 file to
the console.

These opcodes only support the sample structure of SF2 files. The
modulator structure of the SoundFont2 format is not supported in Csound.
Any modulation or processing to the sample data is left to the Csound
user, bypassing all restrictions forced by the SF2 standard.


===========================================================================
sfpreset                                                           *sfpreset*

  Description

Assigns an existing preset of a previously loaded SoundFont2 (SF2)
sample file to an index number. These opcodes allow management the
sample-structure of SF2 files. In order to understand the usage of these
opcodes, the user must have some knowledge of the SF2 format, so a brief
description of this format can be found in the SoundFont2 File Format
Appendix.

sfpreset should be placed in the header section of a Csound orchestra.

  Syntax

ir sfpreset iprog, ibank, ifilhandle, ipreindex

  Initialization

ir -- output to be used by other SF2 opcodes. For sfpreset, ir is
ipreindex.

iprog -- program number of a bank of presets in a SF2 file

ibank -- number of a specific bank of a SF2 file

ifilhandle -- unique number generated by sfload opcode to be used as an
identifier for a SF2 file. Several SF2 files can be loaded and activated
at the same time.

ipreindex -- preset index

  Performance

sfpreset assigns an existing preset of a previously loaded SF2 file to
an index number, to be used later with the opcodes sfplay and sfplaym.
The user must previously know the program and the bank numbers of the
preset in order to fill the corresponding arguments. Any number of
sfpreset instances can be placed in the header section of an orchestra,
each one assigning a different preset belonging to the same (or
different) SF2 file to different index numbers.

These opcodes only support the sample structure of SF2 files. The
modulator structure of the SoundFont2 format is not supported in Csound.
Any modulation or processing to the sample data is left to the Csound
user, bypassing all restrictions forced by the SF2 standard.


===========================================================================
shaker                                                               *shaker*

  Description

Audio output is a tone related to the shaking of a maraca or similar
gourd instrument. The method is a physically inspired model developed
from Perry Cook, but re-coded for Csound.

  Syntax

ares shaker kamp, kfreq, kbeans, kdamp, ktimes [, idecay]

  Initialization

idecay -- If present indicates for how long at the end of the note the
shaker is to be damped. The default value is zero.

  Performance

A note is played on a maraca-like instrument, with the arguments as below.

kamp -- Amplitude of note.

kfreq -- Frequency of note played.

kbeans -- The number of beans in the gourd. A value of 8 seems suitable.

kdamp -- The damping value of the shaker. Values of 0.98 to 1 seems
suitable, with 0.99 a reasonable default.

ktimes -- Number of times shaken.

  Note

The argument knum was redundant, so it was removed in version 3.49.


===========================================================================
shiftin                                                             *shiftin*

  Description

This opcode can be used to push data from an audio variable into a
1-dimensional array. The array needs to be at least ksmps numbers long,
but can be longer. Data is shifted in circularly, with the writing
position moving by ksmps positions every k-cycle. When the array gets
full, the writing position wraps around to the beginning of the array
again (overwriting old positions). Together with the shiftout opcode, it
can form a FIFO queue.

  Syntax

kout[] shiftin asig

  Performance

kout[] -- output array, needs to be at least ksmps numbers long.

asig -- input audio


===========================================================================
shiftout                                                           *shiftout*

  Description

This opcode can be used to push data to an audio variable from a
1-dimensional array. The array needs to be at least ksmps numbers long,
but can be longer. Data is shifted out circularly, with the writing
position moving by ksmps positions every k-cycle. When the array gets
emptied, the writing position wraps around to the beginning of the array
again. Together with the shiftin opcode, it can form a FIFO queue.

  Syntax

asig shiftout kIn[][, ioff]

  Initialization

ioff -- initial read offset position (optional, defaults to 0).

  Performance

kin[] -- input array, needs to be at least ksmps numbers long.

asig -- output audio


===========================================================================
signum                                                               *signum*

  Description

Returns the signum of x returning -1, 0 or 1.

  Syntax

signum(x) (no rate restriction)


===========================================================================
sin                                                                     *sin*

  Description

Returns the sine of x (x in radians).

  Syntax

sin(x) (no rate restriction)


===========================================================================
sinh                                                                   *sinh*

  Description

Returns the hyperbolic sine of x (x in radians).

  Syntax

sinh(x) (no rate restriction)


===========================================================================
sininv                                                               *sininv*

  Description

Returns the arcsine of x (x in radians).

  Syntax

sininv(x) (no rate restriction)


===========================================================================
sinsyn                                                               *sinsyn*

  Description

The sinsyn opcode takes an input containg a TRACKS pv streaming signal
(as generated, for instance by the partials opcode). It resynthesises
the signal using linear amplitude and cubic phase interpolation to drive
a bank of interpolating oscillators with amplitude scaling control.
sinsyn attempts to preserve the phase of the partials in the original
signal and in so doing it does not allow for pitch or timescale
modifications of the signal.

  Syntax

asig sinsyn fin, kscal, kmaxtracks, ifn

  Performance

asig -- output audio rate signal

fin -- input pv stream in TRACKS format

kscal -- amplitude scaling

kmaxtracks -- max number of tracks in sinsynthesis. Limiting this will
cause a non-linear filtering effect, by discarding newer and
higher-frequency tracks (tracks are ordered by start time and ascending
frequency, respectively)

ifn -- function table containing one cycle of a sinusoid (sine or cosine).


===========================================================================
sleighbells                                                     *sleighbells*

  Description

sleighbells is a semi-physical model of a sleighbell sound. It is one of
the PhISEM percussion opcodes. PhISEM (Physically Informed Stochastic
Event Modeling) is an algorithmic approach for simulating collisions of
multiple independent sound producing objects.

  Syntax

ares sleighbells kamp, idettack [, inum] [, idamp] [, imaxshake] [, ifreq] \
      [, ifreq1] [, ifreq2]

  Initialization

idettack -- period of time over which all sound is stopped

inum (optional) -- The number of beads, teeth, bells, timbrels, etc. If
zero, the default value is 32.

idamp (optional) -- the damping factor, as part of this equation:

damping_amount = 0.9994 + (idamp * 0.002)

The default damping_amount is 0.9994 which means that the default value
of idamp is 0. The maximum damping_amount is 1.0 (no damping). This
means the maximum value for idamp is 0.03.

The recommended range for idamp is usually below 75% of the maximum value.

imaxshake (optional, default=0) -- amount of energy to add back into the
system. The value should be in range 0 to 1.

ifreq (optional) -- the main resonant frequency. The default value is 2500.

ifreq1 (optional) -- the first resonant frequency. The default value is
5300.

ifreq2 (optional) -- the second resonant frequency. The default value is
6500.

  Performance

kamp -- Amplitude of output. Note: As these instruments are stochastic,
this is only an approximation.


===========================================================================
slicearray                                                       *slicearray*

  Description

Take a slice of a vector (one-dimensional k-rate array).

  Syntax

karray slicearray kinarray, istart, iend

  Initialization

istart -- index of the first part of the answer.

iend -- index of the first element of the answer.


===========================================================================
slider16                                                           *slider16*

  Description

Creates a bank of 16 different MIDI control message numbers.

  Syntax

i1,...,i16 slider16 ichan, ictlnum1, imin1, imax1, init1, ifn1,..., \
      ictlnum16, imin16, imax16, init16, ifn16

k1,...,k16 slider16 ichan, ictlnum1, imin1, imax1, init1, ifn1,..., \
      ictlnum16, imin16, imax16, init16, ifn16

  Initialization

i1 ... i16 -- output values

ichan -- MIDI channel (1-16)

ictlnum1 ... ictlnum16 -- MIDI control number (0-127)

imin1 ... imin16 -- minimum values for each controller

imax1 ... imax16 -- maximum values for each controller

init1 ... init16 -- initial value for each controller

ifn1 ... ifn16 -- function table for conversion for each controller

  Performance

k1 ... k16 -- output values

slider16 is a bank of MIDI controllers, useful when using MIDI mixer
such as Kawai MM-16 or others for changing whatever sound parameter in
real-time. The raw MIDI control messages at the input port are converted
to agree with iminN and imaxN, and an initial value can be set. Also, an
optional non-interpolated function table with a custom translation curve
is allowed, useful for enabling exponential response curves.

When no function table translation is required, set the ifnN value to 0,
else set ifnN to a valid function table number. When table translation
is enabled (i.e. setting ifnN value to a non-zero number referring to an
already allocated function table), initN value should be set equal to
iminN or imaxN value, else the initial output value will not be the same
as specified in initN argument.

slider16 allows a bank of 16 different MIDI control message numbers.

As the input and output arguments are many, you can split the line using
'\' (backslash) character (new in 3.47 version) to improve the
readability. Using these opcodes is considerably more efficient than
using the separate ones (ctrl7 and tonek) when more controllers are
required.

In the i-rate version of slider16, there is not an initial value input
argument, because the output is gotten directly from current status of
internal controller array of Csound.


===========================================================================
slider16f                                                         *slider16f*

  Description

Creates a bank of 16 different MIDI control message numbers, filtered
before output.

  Syntax

k1,...,k16 slider16f ichan, ictlnum1, imin1, imax1, init1, ifn1, \
      icutoff1,..., ictlnum16, imin16, imax16, init16, ifn16, icutoff16

  Initialization

ichan -- MIDI channel (1-16)

ictlnum1 ... ictlnum16 -- MIDI control number (0-127)

imin1 ... imin16 -- minimum values for each controller

imax1 ... imax16 -- maximum values for each controller

init1 ... init16 -- initial value for each controller

ifn1 ... ifn16 -- function table for conversion for each controller

icutoff1 ... icutoff16 -- low-pass filter cutoff frequency for each
controller

  Performance

k1 ... k16 -- output values

slider16f is a bank of MIDI controllers, useful when using MIDI mixer
such as Kawai MM-16 or others for changing whatever sound parameter in
real-time. The raw MIDI control messages at the input port are converted
to agree with iminN and imaxN, and an initial value can be set. Also, an
optional non-interpolated function table with a custom translation curve
is allowed, useful for enabling exponential response curves.

When no function table translation is required, set the ifnN value to 0,
else set ifnN to a valid function table number. When table translation
is enabled (i.e. setting ifnN value to a non-zero number referring to an
already allocated function table), initN value should be set equal to
iminN or imaxN value, else the initial output value will not be the same
as specified in initN argument.

slider16f allows a bank of 16 different MIDI control message numbers. It
filters the signal before output. This eliminates discontinuities due to
the low resolution of the MIDI (7 bit). The cutoff frequency can be set
separately for each controller (suggested range: .1 to 5 Hz).

As the input and output arguments are many, you can split the line using
'\' (backslash) character (new in 3.47 version) to improve the
readability. Using these opcodes is considerably more efficient than
using the separate ones (ctrl7 and tonek) when more controllers are
required.

  Warning

slider16f does not output the required initial value immediately, but
only after some k-cycles because the filter slightly delays the output.


===========================================================================
slider16table                                                 *slider16table*

  Description

Stores a bank of 16 different MIDI control messages to a table.

  Syntax

kflag slider16table ichan, ioutTable, ioffset, ictlnum1, imin1, imax1, \
      init1, ifn1, .... , ictlnum16, imin16, imax16, init16, ifn16

  Initialization

ichan -- MIDI channel (1-16)

ioutTable -- number of the table that will contain the output

ioffset -- output table offset. A zero means that the output of the
first slider will affect the first table element. A 10 means that the
output of the first slider will affect the 11th table element.

ictlnum1 ... ictlnum16 -- MIDI control number (0-127)

imin1 ... imin16 -- minimum values for each controller

imax1 ... imax16 -- maximum values for each controller

init1 ... init16 -- initial value for each controller

ifn1 ... ifn16 -- function table for conversion for each controller

  Performance

kflag -- a flag that informs if any control-change message in the bank
has been received. In this case kflag is set to 1. Otherwise is set to
zero.

slider16table is a bank of MIDI controllers, useful when using MIDI
mixer such as Kawai MM-16 or others for changing whatever sound
parameter in real-time. The raw MIDI control messages at the input port
are converted to agree with iminN and imaxN, and an initial value can be
set. Also, an optional non-interpolated function table with a custom
translation curve is allowed, useful for enabling exponential response
curves.

When no function table translation is required, set the ifnN value to 0,
else set ifnN to a valid function table number. When table translation
is enabled (i.e. setting ifnN value to a non-zero number referring to an
already allocated function table), initN value should be set equal to
iminN or imaxN value, else the initial output value will not be the same
as specified in initN argument.

slider16table allows a bank of 16 different MIDI control message numbers.

As the input and output arguments are many, you can split the line using
'\' (backslash) character (new in 3.47 version) to improve the
readability. Using these opcodes is considerably more efficient than
using the separate ones (ctrl7 and tonek) when more controllers are
required.

slider16table is very similar to slider16 and sliderN family of opcodes
(see their manual for more information). The actual difference is that
the output is not stored to k-rate variables, but to a table, denoted by
the ioutTable argument. It is possible to define a starting index in
order to use the same table for more than one slider bank (or other
purposes).

It is possible to use this opcode together with FLslidBnk2Setk and
FLslidBnk2, so you can synchronize the position of the MIDI values to
the position of the FLTK valuator widgets of FLslidBnk2. Notice that you
have to specify the same min/max values as well the linear/exponential
responses in both sliderNtable(f) and FLslidBnk2. The exception is when
using table-indexed response instead of a lin/exp response. In this
case, in order to achieve a useful result, the table-indexed response
and actual min/max values must be set only in FLslidBnk2, whereas, in
sliderNtable(f), you have to set a linear response and a minimum of zero
and a maximum of one in all sliders.


===========================================================================
slider16tablef                                               *slider16tablef*

  Description

Stores a bank of 16 different MIDI control messages to a table, filtered
before output.

  Syntax

kflag slider16tablef ichan, ioutTable, ioffset, ictlnum1, imin1, imax1, \
      init1, ifn1, icutoff1, .... , ictlnum16, imin16, imax16, init16, ifn16, icutoff16

  Initialization

ichan -- MIDI channel (1-16)

ioutTable -- number of the table that will contain the output

ioffset -- output table offset. A zero means that the output of the
first slider will affect the first table element. A 10 means that the
output of the first slider will affect the 11th table element.

ictlnum1 ... ictlnum16 -- MIDI control number (0-127)

imin1 ... imin16 -- minimum values for each controller

imax1 ... imax16 -- maximum values for each controller

init1 ... init16 -- initial value for each controller

ifn1 ... ifn16 -- function table for conversion for each controller

icutoff1 ... icutoff16 -- low-pass filter cutoff frequency for each
controller

  Performance

kflag -- a flag that informs if any control-change message in the bank
has been received. In this case kflag is set to 1. Otherwise is set to
zero.

slider16tablef is a bank of MIDI controllers, useful when using MIDI
mixer such as Kawai MM-16 or others for changing whatever sound
parameter in real-time. The raw MIDI control messages at the input port
are converted to agree with iminN and imaxN, and an initial value can be
set. Also, an optional non-interpolated function table with a custom
translation curve is allowed, useful for enabling exponential response
curves.

When no function table translation is required, set the ifnN value to 0,
else set ifnN to a valid function table number. When table translation
is enabled (i.e. setting ifnN value to a non-zero number referring to an
already allocated function table), initN value should be set equal to
iminN or imaxN value, else the initial output value will not be the same
as specified in initN argument.

slider16tablef allows a bank of 16 different MIDI control message
numbers. It filters the signal before output. This eliminates
discontinuities due to the low resolution of the MIDI (7 bit). The
cutoff frequency can be set separately for each controller (suggested
range: .1 to 5 Hz).

As the input and output arguments are many, you can split the line using
'\' (backslash) character (new in 3.47 version) to improve the
readability. Using these opcodes is considerably more efficient than
using the separate ones (ctrl7 and tonek) when more controllers are
required.

slider16tablef is very similar to slider16f and sliderNf family of
opcodes (see their manual for more information). The actual difference
is that the output is not stored to k-rate variables, but to a table,
denoted by the ioutTable argument. It is possible to define a starting
index in order to use the same table for more than one slider bank (or
other purposes).

It is possible to use this opcode together with FLslidBnk2Setk and
FLslidBnk2, so you can synchronize the position of the MIDI values to
the position of the FLTK valuator widgets of FLslidBnk2. Notice that you
have to specify the same min/max values as well the linear/exponential
responses in both sliderNtable(f) and FLslidBnk2. The exception is when
using table-indexed response instead of a lin/exp response. In this
case, in order to achieve a useful result, the table-indexed response
and actual min/max values must be set only in FLslidBnk2, whereas, in
sliderNtable(f), you have to set a linear response and a minimum of zero
and a maximum of one in all sliders.

  Warning

slider16tablef does not output the required initial value immediately,
but only after some k-cycles because the filter slightly delays the output.


===========================================================================
slider32                                                           *slider32*

  Description

Creates a bank of 32 different MIDI control message numbers.

  Syntax

i1,...,i32 slider32 ichan, ictlnum1, imin1, imax1, init1, ifn1,..., \
      ictlnum32, imin32, imax32, init32, ifn32

k1,...,k32 slider32 ichan, ictlnum1, imin1, imax1, init1, ifn1,..., \
      ictlnum32, imin32, imax32, init32, ifn32

  Initialization

i1 ... i32 -- output values

ichan -- MIDI channel (1-16)

ictlnum1 ... ictlnum32 -- MIDI control number (0-127)

imin1 ... imin32 -- minimum values for each controller

imax1 ... imax32 -- maximum values for each controller

init1 ... init32 -- initial value for each controller

ifn1 ... ifn32 -- function table for conversion for each controller

  Performance

k1 ... k32 -- output values

slider32 is a bank of MIDI controllers, useful when using MIDI mixer
such as Kawai MM-16 or others for changing whatever sound parameter in
real-time. The raw MIDI control messages at the input port are converted
to agree with iminN and imaxN, and an initial value can be set. Also, an
optional non-interpolated function table with a custom translation curve
is allowed, useful for enabling exponential response curves.

When no function table translation is required, set the ifnN value to 0,
else set ifnN to a valid function table number. When table translation
is enabled (i.e. setting ifnN value to a non-zero number referring to an
already allocated function table), initN value should be set equal to
iminN or imaxN value, else the initial output value will not be the same
as specified in initN argument.

slider32 allows a bank of 32 different MIDI control message numbers.

As the input and output arguments are many, you can split the line using
'\' (backslash) character (new in 3.47 version) to improve the
readability. Using these opcodes is considerably more efficient than
using the separate ones (ctrl7 and tonek) when more controllers are
required.

In the i-rate version of slider32, there is not an initial value input
argument, because the output is gotten directly from current status of
internal controller array of Csound.


===========================================================================
slider32f                                                         *slider32f*

  Description

Creates a bank of 32 different MIDI control message numbers, filtered
before output.

  Syntax

k1,...,k32 slider32f ichan, ictlnum1, imin1, imax1, init1, ifn1, icutoff1, \
      ..., ictlnum32, imin32, imax32, init32, ifn32, icutoff32

  Initialization

ichan -- MIDI channel (1-16)

ictlnum1 ... ictlnum32 -- MIDI control number (0-127)

imin1 ... imin32 -- minimum values for each controller

imax1 ... imax32 -- maximum values for each controller

init1 ... init32 -- initial value for each controller

ifn1 ... ifn32 -- function table for conversion for each controller

icutoff1 ... icutoff32 -- low-pass filter cutoff frequency for each
controller

  Performance

k1 ... k32 -- output values

slider32f is a bank of MIDI controllers, useful when using MIDI mixer
such as Kawai MM-16 or others for changing whatever sound parameter in
real-time. The raw MIDI control messages at the input port are converted
to agree with iminN and imaxN, and an initial value can be set. Also, an
optional non-interpolated function table with a custom translation curve
is allowed, useful for enabling exponential response curves.

When no function table translation is required, set the ifnN value to 0,
else set ifnN to a valid function table number. When table translation
is enabled (i.e. setting ifnN value to a non-zero number referring to an
already allocated function table), initN value should be set equal to
iminN or imaxN value, else the initial output value will not be the same
as specified in initN argument.

slider32f allows a bank of 32 different MIDI control message numbers. It
filters the signal before output. This eliminates discontinuities due to
the low resolution of the MIDI (7 bit). The cutoff frequency can be set
separately for each controller (suggested range: .1 to 5 Hz).

As the input and output arguments are many, you can split the line using
'\' (backslash) character (new in 3.47 version) to improve the
readability. Using these opcodes is considerably more efficient than
using the separate ones (ctrl7 and tonek) when more controllers are
required.

  Warning

slider32f opcodes do not output the required initial value immediately,
but only after some k-cycles because the filter slightly delays the output.


===========================================================================
slider32table                                                 *slider32table*

  Description

Creates a bank of 32 different MIDI control messages to a table.

  Syntax

kflag slider32table ichan, ioutTable, ioffset, ictlnum1, imin1, \
      imax1, init1, ifn1, .... , ictlnum32, imin32, imax32, init32, ifn32

  Initialization

ichan -- MIDI channel (1-16)

ioutTable -- number of the table that will contain the output

ioffset -- output table offset. A zero means that the output of the
first slider will affect the first table element. A 10 means that the
output of the first slider will affect the 11th table element.

ictlnum1 ... ictlnum32 -- MIDI control number (0-127)

imin1 ... imin32 -- minimum values for each controller

imax1 ... imax32 -- maximum values for each controller

init1 ... init32 -- initial value for each controller

ifn1 ... ifn32 -- function table for conversion for each controller

  Performance

kflag -- a flag that informs if any control-change message in the bank
has been received. In this case kflag is set to 1. Otherwise is set to
zero.

slider32table is a bank of MIDI controllers, useful when using MIDI
mixer such as Kawai MM-16 or others for changing whatever sound
parameter in real-time. The raw MIDI control messages at the input port
are converted to agree with iminN and imaxN, and an initial value can be
set. Also, an optional non-interpolated function table with a custom
translation curve is allowed, useful for enabling exponential response
curves.

When no function table translation is required, set the ifnN value to 0,
else set ifnN to a valid function table number. When table translation
is enabled (i.e. setting ifnN value to a non-zero number referring to an
already allocated function table), initN value should be set equal to
iminN or imaxN value, else the initial output value will not be the same
as specified in initN argument.

slider32table allows a bank of 32 different MIDI control message numbers.

As the input and output arguments are many, you can split the line using
'\' (backslash) character (new in 3.47 version) to improve the
readability. Using these opcodes is considerably more efficient than
using the separate ones (ctrl7 and tonek) when more controllers are
required.

slider32table is very similar to slider32 and sliderN family of opcodes
(see their manual for more information). The actual difference is that
the output is not stored to k-rate variables, but to a table, denoted by
the ioutTable argument. It is possible to define a starting index in
order to use the same table for more than one slider bank (or other
purposes).

It is possible to use this opcode together with FLslidBnk2Setk and
FLslidBnk2, so you can synchronize the position of the MIDI values to
the position of the FLTK valuator widgets of FLslidBnk2. Notice that you
have to specify the same min/max values as well the linear/exponential
responses in both sliderNtable(f) and FLslidBnk2. The exception is when
using table-indexed response instead of a lin/exp response. In this
case, in order to achieve a useful result, the table-indexed response
and actual min/max values must be set only in FLslidBnk2, whereas, in
sliderNtable(f), you have to set a linear response and a minimum of zero
and a maximum of one in all sliders.


===========================================================================
slider32tablef                                               *slider32tablef*

  Description

Stores a bank of 32 different MIDI control messages to a table, filtered
before output.

  Syntax

kflag slider32tablef ichan, ioutTable, ioffset, ictlnum1, imin1, imax1, \
      init1, ifn1, icutoff1, .... , ictlnum32, imin32, imax32, init32, ifn32, icutoff32

  Initialization

ichan -- MIDI channel (1-16)

ioutTable -- number of the table that will contain the output

ioffset -- output table offset. A zero means that the output of the
first slider will affect the first table element. A 10 means that the
output of the first slider will affect the 11th table element.

ictlnum1 ... ictlnum32 -- MIDI control number (0-127)

imin1 ... imin32 -- minimum values for each controller

imax1 ... imax32 -- maximum values for each controller

init1 ... init32 -- initial value for each controller

ifn1 ... ifn32 -- function table for conversion for each controller

icutoff1 ... icutoff32 -- low-pass filter cutoff frequency for each
controller

  Performance

kflag -- a flag that informs if any control-change message in the bank
has been received. In this case kflag is set to 1. Otherwise is set to
zero.

slider32tablef is a bank of MIDI controllers, useful when using MIDI
mixer such as Kawai MM-16 or others for changing whatever sound
parameter in real-time. The raw MIDI control messages at the input port
are converted to agree with iminN and imaxN, and an initial value can be
set. Also, an optional non-interpolated function table with a custom
translation curve is allowed, useful for enabling exponential response
curves.

When no function table translation is required, set the ifnN value to 0,
else set ifnN to a valid function table number. When table translation
is enabled (i.e. setting ifnN value to a non-zero number referring to an
already allocated function table), initN value should be set equal to
iminN or imaxN value, else the initial output value will not be the same
as specified in initN argument.

slider32tablef allows a bank of 32 different MIDI control message
numbers. It filters the signal before output. This eliminates
discontinuities due to the low resolution of the MIDI (7 bit). The
cutoff frequency can be set separately for each controller (suggested
range: .1 to 5 Hz).

As the input and output arguments are many, you can split the line using
'\' (backslash) character (new in 3.47 version) to improve the
readability. Using these opcodes is considerably more efficient than
using the separate ones (ctrl7 and tonek) when more controllers are
required.

slider32tablef is very similar to slider32f and sliderNf family of
opcodes (see their manual for more information). The actual difference
is that the output is not stored to k-rate variables, but to a table,
denoted by the ioutTable argument. It is possible to define a starting
index in order to use the same table for more than one slider bank (or
other purposes).

It is possible to use this opcode together with FLslidBnk2Setk and
FLslidBnk2, so you can synchronize the position of the MIDI values to
the position of the FLTK valuator widgets of FLslidBnk2. Notice that you
have to specify the same min/max values as well the linear/exponential
responses in both sliderNtable(f) and FLslidBnk2. The exception is when
using table-indexed response instead of a lin/exp response. In this
case, in order to achieve a useful result, the table-indexed response
and actual min/max values must be set only in FLslidBnk2, whereas, in
sliderNtable(f), you have to set a linear response and a minimum of zero
and a maximum of one in all sliders.

  Warning

slider32tablef opcodes do not output the required initial value
immediately, but only after some k-cycles because the filter slightly
delays the output.


===========================================================================
slider64                                                           *slider64*

  Description

Creates a bank of 64 different MIDI control message numbers.

  Syntax

i1,...,i64 slider64 ichan, ictlnum1, imin1, imax1, init1, ifn1,..., \
      ictlnum64, imin64, imax64, init64, ifn64

k1,...,k64 slider64 ichan, ictlnum1, imin1, imax1, init1, ifn1,..., \
      ictlnum64, imin64, imax64, init64, ifn64

  Initialization

i1 ... i64 -- output values

ichan -- MIDI channel (1-16)

ictlnum1 ... ictlnum64 -- MIDI control number (0-127)

imin1 ... imin64 -- minimum values for each controller

imax1 ... imax64 -- maximum values for each controller

init1 ... init64 -- initial value for each controller

ifn1 ... ifn64 -- function table for conversion for each controller

  Performance

k1 ... k64 -- output values

slider64 is a bank of MIDI controllers, useful when using MIDI mixer
such as Kawai MM-16 or others for changing whatever sound parameter in
real-time. The raw MIDI control messages at the input port are converted
to agree with iminN and imaxN, and an initial value can be set. Also, an
optional non-interpolated function table with a custom translation curve
is allowed, useful for enabling exponential response curves.

When no function table translation is required, set the ifnN value to 0,
else set ifnN to a valid function table number. When table translation
is enabled (i.e. setting ifnN value to a non-zero number referring to an
already allocated function table), initN value should be set equal to
iminN or imaxN value, else the initial output value will not be the same
as specified in initN argument.

slider64 allows a bank of 64 different MIDI control message numbers.

As the input and output arguments are many, you can split the line using
'\' (backslash) character (new in 3.47 version) to improve the
readability. Using these opcodes is considerably more efficient than
using the separate ones (ctrl7 and tonek) when more controllers are
required.

In the i-rate version of slider64, there is not an initial value input
argument, because the output is gotten directly from current status of
internal controller array of Csound.


===========================================================================
slider64f                                                         *slider64f*

  Description

Creates a bank of 64 different MIDI control message numbers, filtered
before output.

  Syntax

k1,...,k64 slider64f ichan, ictlnum1, imin1, imax1, init1, ifn1, \
      icutoff1,..., ictlnum64, imin64, imax64, init64, ifn64, icutoff64

  Initialization

ichan -- MIDI channel (1-16)

ictlnum1 ... ictlnum64 -- MIDI control number (0-127)

imin1 ... imin64 -- minimum values for each controller

imax1 ... imax64 -- maximum values for each controller

init1 ... init64 -- initial value for each controller

ifn1 ... ifn64 -- function table for conversion for each controller

icutoff1 ... icutoff64 -- low-pass filter cutoff frequency for each
controller

  Performance

k1 ... k64 -- output values

slider64f is a bank of MIDI controllers, useful when using MIDI mixer
such as Kawai MM-16 or others for changing whatever sound parameter in
real-time. The raw MIDI control messages at the input port are converted
to agree with iminN and imaxN, and an initial value can be set. Also, an
optional non-interpolated function table with a custom translation curve
is allowed, useful for enabling exponential response curves.

When no function table translation is required, set the ifnN value to 0,
else set ifnN to a valid function table number. When table translation
is enabled (i.e. setting ifnN value to a non-zero number referring to an
already allocated function table), initN value should be set equal to
iminN or imaxN value, else the initial output value will not be the same
as specified in initN argument.

slider64f allows a bank of 64 different MIDI control message numbers. It
filters the signal before output. This eliminates discontinuities due to
the low resolution of the MIDI (7 bit). The cutoff frequency can be set
separately for each controller (suggested range: .1 to 5 Hz).

As the input and output arguments are many, you can split the line using
'\' (backslash) character (new in 3.47 version) to improve the
readability. Using these opcodes is considerably more efficient than
using the separate ones (ctrl7 and tonek) when more controllers are
required.

  Warning

slider64f opcodes do not output the required initial value immediately,
but only after some k-cycles because the filter slightly delays the output.


===========================================================================
slider64table                                                 *slider64table*

  Description

Creates a bank of 64 different MIDI control messages to a table.

  Syntax

kflag slider64table ichan, ioutTable, ioffset, ictlnum1, imin1, \
      imax1, init1, ifn1, .... , ictlnum64, imin64, imax64, init64, ifn64

  Initialization

ichan -- MIDI channel (1-16)

ioutTable -- number of the table that will contain the output

ioffset -- output table offset. A zero means that the output of the
first slider will affect the first table element. A 10 means that the
output of the first slider will affect the 11th table element.

ictlnum1 ... ictlnum64 -- MIDI control number (0-127)

imin1 ... imin64 -- minimum values for each controller

imax1 ... imax64 -- maximum values for each controller

init1 ... init64 -- initial value for each controller

ifn1 ... ifn64 -- function table for conversion for each controller

  Performance

kflag -- a flag that informs if any control-change message in the bank
has been received. In this case kflag is set to 1. Otherwise is set to
zero.

slider64table is a bank of MIDI controllers, useful when using MIDI
mixer such as Kawai MM-16 or others for changing whatever sound
parameter in real-time. The raw MIDI control messages at the input port
are converted to agree with iminN and imaxN, and an initial value can be
set. Also, an optional non-interpolated function table with a custom
translation curve is allowed, useful for enabling exponential response
curves.

When no function table translation is required, set the ifnN value to 0,
else set ifnN to a valid function table number. When table translation
is enabled (i.e. setting ifnN value to a non-zero number referring to an
already allocated function table), initN value should be set equal to
iminN or imaxN value, else the initial output value will not be the same
as specified in initN argument.

slider64table allows a bank of 64 different MIDI control message numbers.

As the input and output arguments are many, you can split the line using
'\' (backslash) character (new in 3.47 version) to improve the
readability. Using these opcodes is considerably more efficient than
using the separate ones (ctrl7 and tonek) when more controllers are
required.

slider64table is very similar to slider64 and sliderN family of opcodes
(see their manual for more information). The actual difference is that
the output is not stored to k-rate variables, but to a table, denoted by
the ioutTable argument. It is possible to define a starting index in
order to use the same table for more than one slider bank (or other
purposes).

It is possible to use this opcode together with FLslidBnk2Setk and
FLslidBnk2, so you can synchronize the position of the MIDI values to
the position of the FLTK valuator widgets of FLslidBnk2. Notice that you
have to specify the same min/max values as well the linear/exponential
responses in both sliderNtable(f) and FLslidBnk2. The exception is when
using table-indexed response instead of a lin/exp response. In this
case, in order to achieve a useful result, the table-indexed response
and actual min/max values must be set only in FLslidBnk2, whereas, in
sliderNtable(f), you have to set a linear response and a minimum of zero
and a maximum of one in all sliders.


===========================================================================
slider64tablef                                               *slider64tablef*

  Description

Stores a bank of 64 different MIDI MIDI control messages to a table,
filtered before output.

  Syntax

kflag slider64tablef ichan, ioutTable, ioffset, ictlnum1, imin1, imax1, \
      init1, ifn1, icutoff1, .... , ictlnum64, imin64, imax64, init64, ifn64, icutoff64

  Initialization

ichan -- MIDI channel (1-16)

ioutTable -- number of the table that will contain the output

ioffset -- output table offset. A zero means that the output of the
first slider will affect the first table element. A 10 means that the
output of the first slider will affect the 11th table element.

ictlnum1 ... ictlnum64 -- MIDI control number (0-127)

imin1 ... imin64 -- minimum values for each controller

imax1 ... imax64 -- maximum values for each controller

init1 ... init64 -- initial value for each controller

ifn1 ... ifn64 -- function table for conversion for each controller

icutoff1 ... icutoff64 -- low-pass filter cutoff frequency for each
controller

  Performance

kflag -- a flag that informs if any control-change message in the bank
has been received. In this case kflag is set to 1. Otherwise is set to
zero.

slider64tablef is a bank of MIDI controllers, useful when using MIDI
mixer such as Kawai MM-16 or others for changing whatever sound
parameter in real-time. The raw MIDI control messages at the input port
are converted to agree with iminN and imaxN, and an initial value can be
set. Also, an optional non-interpolated function table with a custom
translation curve is allowed, useful for enabling exponential response
curves.

When no function table translation is required, set the ifnN value to 0,
else set ifnN to a valid function table number. When table translation
is enabled (i.e. setting ifnN value to a non-zero number referring to an
already allocated function table), initN value should be set equal to
iminN or imaxN value, else the initial output value will not be the same
as specified in initN argument.

slider64tablef allows a bank of 64 different MIDI control message
numbers. It filters the signal before output. This eliminates
discontinuities due to the low resolution of the MIDI (7 bit). The
cutoff frequency can be set separately for each controller (suggested
range: .1 to 5 Hz).

As the input and output arguments are many, you can split the line using
'\' (backslash) character (new in 3.47 version) to improve the
readability. Using these opcodes is considerably more efficient than
using the separate ones (ctrl7 and tonek) when more controllers are
required.

slider64tablef is very similar to slider64f and sliderN family of
opcodes (see their manual for more information). The actual difference
is that the output is not stored to k-rate variables, but to a table,
denoted by the ioutTable argument. It is possible to define a starting
index in order to use the same table for more than one slider bank (or
other purposes).

It is possible to use this opcode together with FLslidBnk2Setk and
FLslidBnk2, so you can synchronize the position of the MIDI values to
the position of the FLTK valuator widgets of FLslidBnk2. Notice that you
have to specify the same min/max values as well the linear/exponential
responses in both sliderNtable(f) and FLslidBnk2. The exception is when
using table-indexed response instead of a lin/exp response. In this
case, in order to achieve a useful result, the table-indexed response
and actual min/max values must be set only in FLslidBnk2, whereas, in
sliderNtable(f), you have to set a linear response and a minimum of zero
and a maximum of one in all sliders.

  Warning

slider64tablef opcodes do not output the required initial value
immediately, but only after some k-cycles because the filter slightly
delays the output.


===========================================================================
slider8                                                             *slider8*

  Description

Creates a bank of 8 different MIDI control message numbers.

  Syntax

i1,...,i8 slider8 ichan, ictlnum1, imin1, imax1, init1, ifn1,..., \
      ictlnum8, imin8, imax8, init8, ifn8

k1,...,k8 slider8 ichan, ictlnum1, imin1, imax1, init1, ifn1,..., \
      ictlnum8, imin8, imax8, init8, ifn8

  Initialization

i1 ... i8 -- output values

ichan -- MIDI channel (1-16)

ictlnum1 ... ictlnum8 -- MIDI control number (0-127)

imin1 ... imin8 -- minimum values for each controller

imax1 ... imax8 -- maximum values for each controller

init1 ... init8 -- initial value for each controller

ifn1 ... ifn8 -- function table for conversion for each controller

  Performance

k1 ... k8 -- output values

slider8 is a bank of MIDI controllers, useful when using MIDI mixer such
as Kawai MM-16 or others for changing whatever sound parameter in
real-time. The raw MIDI control messages at the input port are converted
to agree with iminN and imaxN, and an initial value can be set. Also, an
optional non-interpolated function table with a custom translation curve
is allowed, useful for enabling exponential response curves.

When no function table translation is required, set the ifnN value to 0,
else set ifnN to a valid function table number. When table translation
is enabled (i.e. setting ifnN value to a non-zero number referring to an
already allocated function table), initN value should be set equal to
iminN or imaxN value, else the initial output value will not be the same
as specified in initN argument.

slider8 allows a bank of 8 different MIDI control message numbers.

As the input and output arguments are many, you can split the line using
'\' (backslash) character (new in 3.47 version) to improve the
readability. Using these opcodes is considerably more efficient than
using the separate ones (ctrl7 and tonek) when more controllers are
required.

In the i-rate version of slider8, there is not an initial value input
argument, because the output is gotten directly from current status of
internal controller array of Csound.


===========================================================================
slider8f                                                           *slider8f*

  Description

Creates a bank of 8 different MIDI control message numbers, filtered
before output.

  Syntax

k1,...,k8 slider8f ichan, ictlnum1, imin1, imax1, init1, ifn1, icutoff1, \
      ..., ictlnum8, imin8, imax8, init8, ifn8, icutoff8

  Initialization

ichan -- MIDI channel (1-16)

ictlnum1 ... ictlnum8 -- MIDI control number (0-127)

imin1 ... imin8 -- minimum values for each controller

imax1 ... imax8 -- maximum values for each controller

init1 ... init8 -- initial value for each controller

ifn1 ... ifn8 -- function table for conversion for each controller

icutoff1 ... icutoff8 -- low-pass filter cutoff frequency for each
controller

  Performance

k1 ... k8 -- output values

slider8f is a bank of MIDI controllers, useful when using MIDI mixer
such as Kawai MM-16 or others for changing whatever sound parameter in
real-time. The raw MIDI control messages at the input port are converted
to agree with iminN and imaxN, and an initial value can be set. Also, an
optional non-interpolated function table with a custom translation curve
is allowed, useful for enabling exponential response curves.

When no function table translation is required, set the ifnN value to 0,
else set ifnN to a valid function table number. When table translation
is enabled (i.e. setting ifnN value to a non-zero number referring to an
already allocated function table), initN value should be set equal to
iminN or imaxN value, else the initial output value will not be the same
as specified in initN argument.

slider8f allows a bank of 8 different MIDI control message numbers. It
filters the signal before output. This eliminates discontinuities due to
the low resolution of the MIDI (7 bit). The cutoff frequency can be set
separately for each controller (suggested range: .1 to 5 Hz).

As the input and output arguments are many, you can split the line using
'\' (backslash) character (new in 3.47 version) to improve the
readability. Using these opcodes is considerably more efficient than
using the separate ones (ctrl7 and tonek) when more controllers are
required.

  Warning

slider8f opcodes do not output the required initial value immediately,
but only after some k-cycles because the filter slightly delays the output.


===========================================================================
slider8table                                                   *slider8table*

  Description

Stores a bank of 8 different MIDI control messages to a table.

  Syntax

kflag slider8table ichan, ioutTable, ioffset, ictlnum1, imin1, imax1, \
      init1, ifn1,..., ictlnum8, imin8, imax8, init8, ifn8

  Initialization

i1 ... i8 -- output values

ichan -- MIDI channel (1-16)

ioutTable -- number of the table that will contain the output

ioffset -- output table offset. A zero means that the output of the
first slider will affect the first table element. A 10 means that the
output of the first slider will affect the 11th table element.

ictlnum1 ... ictlnum8 -- MIDI control number (0-127)

imin1 ... imin8 -- minimum values for each controller

imax1 ... imax8 -- maximum values for each controller

init1 ... init8 -- initial value for each controller

ifn1 ... ifn8 -- function table for conversion for each controller

  Performance

kflag -- a flag that informs if any control-change message in the bank
has been received. In this case kflag is set to 1. Otherwise is set to
zero.

slider8table handles a bank of MIDI controllers, useful when using MIDI
mixer such as Kawai MM-16 or others for changing whatever sound
parameter in real-time. The raw MIDI control messages at the input port
are converted to agree with iminN and imaxN, and an initial value can be
set. Also, an optional non-interpolated function table with a custom
translation curve is allowed, useful for enabling exponential response
curves.

When no function table translation is required, set the ifnN value to 0,
else set ifnN to a valid function table number. When table translation
is enabled (i.e. setting ifnN value to a non-zero number referring to an
already allocated function table), initN value should be set equal to
iminN or imaxN value, else the initial output value will not be the same
as specified in initN argument.

slider8table allows a bank of 8 different MIDI control message numbers.

As the input and output arguments are many, you can split the line using
'\' (backslash) character (new in 3.47 version) to improve the
readability. Using these opcodes is considerably more efficient than
using the separate ones (ctrl7 and tonek) when more controllers are
required.

slider8table is very similar to slider8 and sliderN family of opcodes
(see their manual for more information). The actual difference is that
the output is not stored to k-rate variables, but to a table, denoted by
the ioutTable argument. It is possible to define a starting index in
order to use the same table for more than one slider bank (or other
purposes).

It is possible to use this opcode together with FLslidBnk2Setk and
FLslidBnk2, so you can synchronize the position of the MIDI values to
the position of the FLTK valuator widgets of FLslidBnk2. Notice that you
have to specify the same min/max values as well the linear/exponential
responses in both sliderNtable(f) and FLslidBnk2. The exception is when
using table-indexed response instead of a lin/exp response. In this
case, in order to achieve a useful result, the table-indexed response
and actual min/max values must be set only in FLslidBnk2, whereas, in
sliderNtable(f), you have to set a linear response and a minimum of zero
and a maximum of one in all sliders.


===========================================================================
slider8tablef                                                 *slider8tablef*

  Description

Stores a bank of 8 different MIDI control messages to a table, filtered
before output.

  Syntax

kflag slider8tablef ichan, ioutTable, ioffset, ictlnum1, imin1, imax1, \
      init1, ifn1, icutoff1, .... , ictlnum8, imin8, imax8, init8, ifn8, icutoff8

  Initialization

ichan -- MIDI channel (1-16)

ioutTable -- number of the table that will contain the output

ioffset -- output table offset. A zero means that the output of the
first slider will affect the first table element. A 10 means that the
output of the first slider will affect the 11th table element.

ictlnum1 ... ictlnum8 -- MIDI control number (0-127)

imin1 ... imin8 -- minimum values for each controller

imax1 ... imax8 -- maximum values for each controller

init1 ... init8 -- initial value for each controller

ifn1 ... ifn8 -- function table for conversion for each controller

icutoff1 ... icutoff8 -- low-pass filter cutoff frequency for each
controller

  Performance

kflag -- a flag that informs if any control-change message in the bank
has been received. In this case kflag is set to 1. Otherwise is set to
zero.

slider8tablef is a bank of MIDI controllers, useful when using MIDI
mixer such as Kawai MM-16 or others for changing whatever sound
parameter in real-time. The raw MIDI control messages at the input port
are converted to agree with iminN and imaxN, and an initial value can be
set. Also, an optional non-interpolated function table with a custom
translation curve is allowed, useful for enabling exponential response
curves.

When no function table translation is required, set the ifnN value to 0,
else set ifnN to a valid function table number. When table translation
is enabled (i.e. setting ifnN value to a non-zero number referring to an
already allocated function table), initN value should be set equal to
iminN or imaxN value, else the initial output value will not be the same
as specified in initN argument.

slider8tablef allows a bank of 8 different MIDI control message numbers.
It filters the signal before output. This eliminates discontinuities due
to the low resolution of the MIDI (7 bit). The cutoff frequency can be
set separately for each controller (suggested range: .1 to 5 Hz).

As the input and output arguments are many, you can split the line using
'\' (backslash) character (new in 3.47 version) to improve the
readability. Using these opcodes is considerably more efficient than
using the separate ones (ctrl7 and tonek) when more controllers are
required.

slider8tablef is very similar to slider8f and sliderNf family of opcodes
(see their manual for more information). The actual difference is that
the output is not stored to k-rate variables, but to a table, denoted by
the ioutTable argument. It is possible to define a starting index in
order to use the same table for more than one slider bank (or other
purposes).

It is possible to use this opcode together with FLslidBnk2Setk and
FLslidBnk2, so you can synchronize the position of the MIDI values to
the position of the FLTK valuator widgets of FLslidBnk2. Notice that you
have to specify the same min/max values as well the linear/exponential
responses in both sliderNtable(f) and FLslidBnk2. The exception is when
using table-indexed response instead of a lin/exp response. In this
case, in order to achieve a useful result, the table-indexed response
and actual min/max values must be set only in FLslidBnk2, whereas, in
sliderNtable(f), you have to set a linear response and a minimum of zero
and a maximum of one in all sliders.

  Warning

slider8tablef opcodes do not output the required initial value
immediately, but only after some k-cycles because the filter slightly
delays the output.


===========================================================================
sliderKawai                                                     *sliderKawai*

  Description

Creates a bank of 16 different MIDI control message numbers from a KAWAI
MM-16 midi mixer.

  Syntax

k1, k2, ...., k16 sliderKawai imin1, imax1, init1, ifn1, \
      imin2, imax2, init2, ifn2, ..., imin16, imax16, init16, ifn16

  Initialization

imin1 ... imin16 -- minimum values for each controller

imax1 ... imax16 -- maximum values for each controller

init1 ... init16 -- initial value for each controller

ifn1 ... ifn16 -- function table for conversion for each controller

  Performance

k1 ... k16 -- output values

The opcode sliderKawai is equivalent to slider16, but it has the
controller and channel numbers (ichan and ictlnum) hard-coded to make
for quick compatiblity with the KAWAI MM-16 midi mixer. This device
doesn't allow changing the midi message associated to each slider. It
can only output on control 7 for each fader on a separate midi channel.
This opcode is a quick way of assigning the mixer's 16 faders to k-rate
variables in csound.


===========================================================================
sndloop                                                             *sndloop*

  Description

This opcode records input audio and plays it back in a loop with
user-defined duration and crossfade time. It also allows the pitch of
the loop to be controlled, including reversed playback.

  Syntax

asig, krec sndloop ain, kpitch, ktrig, idur, ifad

  Initialization

idur -- loop duration in seconds

ifad -- crossfade duration in seconds

  Performance

asig -- output sig

krec -- 'rec on' signal, 1 when recording, 0 otherwise

kpitch -- pitch control (transposition ratio); negative values play the
loop back in reverse

ktrig -- trigger signal: when 0, processing is bypassed. When switched
on (ktrig >= 1), the opcode starts recording until the loop memory is
full. It then plays the looped sound until it is switched off again
(ktrig = 0). Another recording can start again with ktrig >= 1.


===========================================================================
sndwarp                                                             *sndwarp*

  Description

sndwarp reads sound samples from a table and applies time-stretching
and/or pitch modification. Time and frequency modification are
independent from one another. For example, a sound can be stretched in
time while raising the pitch!

The window size and overlap arguments are important to the result and
should be experimented with. In general they should be as small as
possible. For example, start with iwsize=sr/10 and ioverlap=15. Try
irandw=iwsize*0.2. If you can get away with less overlaps, the program
will be faster. But too few may cause an audible flutter in the
amplitude. The algorithm reacts differently depending upon the input
sound and there are no fixed rules for the best use in all
circumstances. But with proper tuning, excellent results can be achieved.

  Syntax

ares [, ac] sndwarp xamp, xtimewarp, xresample, ifn1, ibeg, iwsize, \
      irandw, ioverlap, ifn2, itimemode

  Initialization

ifn1 -- the number of the table holding the sound samples which will be
subjected to the sndwarp processing. GEN01 is the appropriate function
generator to use to store the sound samples from a pre-existing soundfile.

ibeg -- the time in seconds to begin reading in the table (or
soundfile). When itimemode is non- zero, the value of xtimewarp is
offset by ibeg.

iwsize -- the window size in samples used in the time scaling algorithm.

irandw -- the bandwidth of a random number generator. The random numbers
will be added to iwsize.

ioverlap -- determines the density of overlapping windows.

ifn2 -- a function used to shape the window. It is usually used to
create a ramp of some kind from zero at the beginning and back down to
zero at the end of each window. Try using a half sine (i.e.: f1 0 16384
9 .5 1 0) which works quite well. Other shapes can also be used.

  Performance

ares -- the single channel of output from the sndwarp unit generator.
sndwarp assumes that the function table holding the sampled signal is a
mono one. This simply means that sndwarp will index the table by
single-sample frame increments. The user must be aware then that if a
stereo signal is used with sndwarp, time and pitch will be altered
accordingly.

ac (optional) -- a single-layer (no overlaps), unwindowed versions of
the time and/or pitch altered signal. They are supplied in order to be
able to balance the amplitude of the signal output, which typically
contains many overlapping and windowed versions of the signal, with a
clean version of the time-scaled and pitch-shifted signal. The sndwarp
process can cause noticeable changes in amplitude, (up and down), due to
a time differential between the overlaps when time-shifting is being
done. When used with a balance unit, ac can greatly enhance the quality
of sound.

xamp -- the value by which to scale the amplitude (see note on the use
of this when using ac).

xtimewarp -- determines how the input signal will be stretched or shrunk
in time. There are two ways to use this argument depending upon the
value given for itimemode. When the value of itimemode is 0, xtimewarp
will scale the time of the sound. For example, a value of 2 will stretch
the sound by 2 times. When itimemode is any non-zero value then
xtimewarp is used as a time pointer in a similar way in which the time
pointer works in lpread and pvoc. An example below illustrates this. In
both cases, the pitch will not be altered by this process. Pitch
shifting is done independently using xresample.

xresample -- the factor by which to change the pitch of the sound. For
example, a value of 2 will produce a sound one octave higher than the
original. The timing of the sound, however, will not be altered.


===========================================================================
sndwarpst                                                         *sndwarpst*

  Description

sndwarpst reads stereo sound samples from a table and applies
time-stretching and/or pitch modification. Time and frequency
modification are independent from one another. For example, a sound can
be stretched in time while raising the pitch!

The window size and overlap arguments are important to the result and
should be experimented with. In general they should be as small as
possible. For example, start with iwsize=sr/10 and ioverlap=15. Try
irandw=iwsize*.2. If you can get away with less overlaps, the program
will be faster. But too few may cause an audible flutter in the
amplitude. The algorithm reacts differently depending upon the input
sound and there are no fixed rules for the best use in all
circumstances. But with proper tuning, excellent results can be achieved.

  Syntax

ar1, ar2 [,ac1] [, ac2] sndwarpst xamp, xtimewarp, xresample, ifn1, \
      ibeg, iwsize, irandw, ioverlap, ifn2, itimemode

  Initialization

ifn1 -- the number of the table holding the sound samples which will be
subjected to the sndwarpst processing. GEN01 is the appropriate function
generator to use to store the sound samples from a pre-existing soundfile.

ibeg -- the time in seconds to begin reading in the table (or
soundfile). When itimemode is non-zero, the value of xtimewarp is offset
by ibeg.

iwsize -- the window size in samples used in the time scaling algorithm.

irandw -- the bandwidth of a random number generator. The random numbers
will be added to iwsize.

ioverlap -- determines the density of overlapping windows.

ifn2 -- a function used to shape the window. It is usually used to
create a ramp of some kind from zero at the beginning and back down to
zero at the end of each window. Try using a half a sine (i.e.: f1 0
16384 9 .5 1 0) which works quite well. Other shapes can also be used.

  Performance

ar1, ar2 -- ar1 and ar2 are the stereo (left and right) outputs from
sndwarpst. sndwarpst assumes that the function table holding the sampled
signal is a stereo one. sndwarpst will index the table by a two-sample
frame increment. The user must be aware then that if a mono signal is
used with sndwarpst, time and pitch will be altered accordingly.

ac1, ac2 -- ac1 and ac2 are single-layer (no overlaps), unwindowed
versions of the time and/or pitch altered signal. They are supplied in
order to be able to balance the amplitude of the signal output, which
typically contains many overlapping and windowed versions of the signal,
with a clean version of the time-scaled and pitch-shifted signal. The
sndwarpst process can cause noticeable changes in amplitude, (up and
down), due to a time differential between the overlaps when
time-shifting is being done. When used with a balance unit, ac1 and ac2
can greatly enhance the quality of sound. They are optional, but note
that they must both be present in the syntax (use both or neither). An
example of how to use this is given below.

xamp -- the value by which to scale the amplitude (see note on the use
of this when using ac1 and ac2).

xtimewarp -- determines how the input signal will be stretched or shrunk
in time. There are two ways to use this argument depending upon the
value given for itimemode. When the value of itimemode is 0, xtimewarp
will scale the time of the sound. For example, a value of 2 will stretch
the sound by 2 times. When itimemode is any non-zero value then
xtimewarp is used as a time pointer in a similar way in which the time
pointer works in lpread and pvoc. An example below illustrates this. In
both cases, the pitch will not be altered by this process. Pitch
shifting is done independently using xresample.

xresample -- the factor by which to change the pitch of the sound. For
example, a value of 2 will produce a sound one octave higher than the
original. The timing of the sound, however, will not be altered.


===========================================================================
sockrecv                                                           *sockrecv*

  Description

Receives directly using the UDP (sockrecv and sockrecvs) or TCP (strecv)
protocol onto a network. The data is not subject to any encoding or
special routing. The sockrecvs opcode receives a stereo signal interleaved.

  Syntax

asig sockrecv iport, ilength

ksig sockrecv iport, ilength

asigl, asigr sockrecvs iport, ilength

asig strecv Sipaddr, iport

  Initialization

Sipaddr -- a string that is the IP address of the sender in standard
4-octet dotted form.

iport -- the number of the port that is used for the communication.

ilength -- the length of the individual packets in UDP transmission.
This number must be sufficiently small to fit a single MTU, which is set
to the save value of 1456. In UDP transmissions the sender and receiver
needs agree on this value

  Performance

asig, asigl, asigr -- audio data to be received. ksig -- control data to
be received.


===========================================================================
socksend                                                           *socksend*

  Description

Transmits data directly using the UDP (socksend and socksends) or TCP
(stsend) protocol onto a network. The data is not subject to any
encoding or special routing. The socksends opcode send a stereo signal
interleaved.

  Syntax

socksend asig, Sipaddr, iport, ilength

socksend ksig, Sipaddr, iport, ilength

socksends asigl, asigr, Sipaddr, iport,
    ilength

stsend asig, Sipaddr, iport

  Initialization

Sipaddr -- a string that is the IP address of the receiver in standard
4-octet dotted form.

iport -- the number of the port that is used for the communication.

ilength -- the length of the individual packets in UDP transmission.
This number must be sufficiently small to fit a single MTU, which is set
to the save value of 1456. In UDP transmissions the receiver needs to
know this value

  Performance

asig, ksig, asigl, asigr -- data to be transmitted.


===========================================================================
soundin                                                             *soundin*

  Description

Reads audio data from an external device or stream. Up to 24 channels
may be read before v5.14, extended to 40 in later versions.

  Syntax

ar1[, ar2[, ar3[, ... a24]]] soundin ifilcod [, iskptim] [, iformat] \
      [, iskipinit] [, ibufsize]

  Initialization

ifilcod -- integer or character-string denoting the source soundfile
name. An integer denotes the file soundin.filcod; a character-string (in
double quotes, spaces permitted) gives the filename itself, optionally a
full pathname. If not a full path, the named file is sought first in the
current directory, then in that given by the environment variable SSDIR
(if defined) then by SFDIR. See also GEN01.

iskptim (optional, default=0) -- time in seconds of input sound to be
skipped. The default value is 0. In csound 5.00 and later, this may be
negative to add a delay instead of skipping time.

iformat (optional, default=0) -- specifies the audio data file format:

  * 1 = 8-bit signed char (high-order 8 bits of a 16-bit integer)

  * 2 = 8-bit A-law bytes

  * 3 = 8-bit U-law bytes

  * 4 = 16-bit short integers

  * 5 = 32-bit long integers

  * 6 = 32-bit floats

  * 7 = 8-bit unsigned int (not available in Csound versions older than
    5.00)

  * 8 = 24-bit int (not available in Csound versions older than 5.00)

  * 9 = 64-bit doubles (not available in Csound versions older than 5.00)

iskipinit -- switches off all initialisation if non zero (default=0).
This was introduced in 4_23f13 and csound5.

ibufsize -- buffer size in mono samples (not sample frames). Not
available in Csound versions older than 5.00. The default buffer size is
2048.

If iformat = 0 it is taken from the soundfile header, and if no header
from the Csound -o command-line flag. The default value is 0.

  Performance

soundin is functionally an audio generator that derives its signal from
a pre-existing file. The number of channels read in is controlled by the
number of result cells, a1, a2, etc., which must match that of the input
file. A soundin opcode opens this file whenever the host instrument is
initialized, then closes it again each time the instrument is turned off.

There can be any number of soundin opcodes within a single instrument or
orchestra. Two or more of them can read simultaneously from the same
external file.

[Caution]       Note to Windows users

Windows users typically use back-slashes, “\”, when specifying the paths
of their files. As an example, a Windows user might use the path
“c:\music\samples\loop001.wav”. This is problematic because back-slashes
are normally used to specify special characters.

To correctly specify this path in Csound, one may alternately:

  * Use forward slashes: c:/music/samples/loop001.wav

  * Use back-slash special characters, “\\”: c:\\music\\samples\\loop001.wav


===========================================================================
space                                                                 *space*

  Description

space takes an input signal and distributes it among 4 channels using
Cartesian xy coordinates to calculate the balance of the outputs. The xy
coordinates can be defined in a separate text file and accessed through
a Function statement in the score using Gen28, or they can be specified
using the optional kx, ky arguments. The advantages to the former are:

 1. A graphic user interface can be used to draw and edit the trajectory
    through the Cartesian plane

 2. The file format is in the form time1 X1 Y1 time2 X2 Y2 time3 X3 Y3
    allowing the user to define a time-tagged trajectory

space then allows the user to specify a time pointer (much as is used
for pvoc, lpread and some other units) to have detailed control over the
final speed of movement.

  Syntax

a1, a2, a3, a4  space asig, ifn, ktime, kreverbsend, kx, ky

  Initialization

ifn -- number of the stored function created using Gen28. This function
generator reads a text file which contains sets of three values
representing the xy coordinates and a time-tag for when the signal
should be placed at that location. The file should look like:

  0       -1       1
  1        1       1
  2        4       4
  2.1     -4      -4
  3       10     -10
  5      -40       0

If that file were named “move” then the Gen28 call in the score would like:

  f1 0 0 28 "move"

Gen28 takes 0 as the size and automatically allocates memory. It creates
values to 10 milliseconds of resolution. So in this case there will be
500 values created by interpolating X1 to X2 to X3 and so on, and Y1 to
Y2 to Y3 and so on, over the appropriate number of values that are
stored in the function table. In the above example, the sound will begin
in the left front, over 1 second it will move to the right front, over
another second it move further into the distance but still in the right
front, then in just 1/10th of a second it moves to the left rear, a bit
distant. Finally over the last .9 seconds the sound will move to the
right rear, moderately distant, and it comes to rest between the two
left channels (due west!), quite distant. Since the values in the table
are accessed through the use of a time-pointer in the space unit, the
actual timing can be made to follow the file's timing exactly or it can
be made to go faster or slower through the same trajectory. If you have
access to the GUI that allows one to draw and edit the files, there is
no need to create the text files manually. But as long as the file is
ASCII and in the format shown above, it doesn't matter how it is made!

  Important

If ifn is 0, then space will take its values for the xy coordinates from
kx and ky.

  Performance

The configuration of the xy coordinates in space places the signal in
the following way:

  * a1 is -1, 1

  * a2 is 1, 1

  * a3 is -1, -1

  * a4 is 1, -1

This assumes a loudspeaker set up as a1 is left front, a2 is right
front, a3 is left back, a4 is right back. Values greater than 1 will
result in sounds being attenuated, as if in the distance. space
considers the speakers to be at a distance of 1; smaller values of xy
can be used, but space will not amplify the signal in this case. It
will, however balance the signal so that it can sound as if it were
within the 4 speaker space. x=0, y=1, will place the signal equally
balanced between left and right front channels, x=y=0 will place the
signal equally in all 4 channels, and so on. Although there must be 4
output signals from space, it can be used in a 2 channel orchestra. If
the xy's are kept so that y>=1, it should work well to do panning and
fixed localization in a stereo field.

asig -- input audio signal.

ktime -- index into the table containing the xy coordinates. If used like:

  ktime           line  0, 5, 5
  a1, a2, a3, a4  space asig, 1, ktime, ...

with the file “move” described above, the speed of the signal's movement
will be exactly as described in that file. However:

  ktime           line  0, 10, 5

the signal will move at half the speed specified. Or in the case of:

  ktime           line  5, 15, 0

the signal will move in the reverse direction as specified and 3 times
slower! Finally:

  ktime           line  2, 10, 3

will cause the signal to move only from the place specified in line 3 of
the text file to the place specified in line 5 of the text file, and it
will take 10 seconds to do it.

kreverbsend -- the percentage of the direct signal that will be factored
along with the distance as derived from the xy coordinates to calculate
signal amounts that can be sent to reverb units such as reverb, or reverb2.

kx, ky -- when ifn is 0, space and spdist will use these values as the
xy coordinates to localize the signal.


===========================================================================
spat3d                                                               *spat3d*

  Description

This opcode positions the input sound in a 3D space, with optional
simulation of room acoustics, in various output formats. spat3d allows
moving the sound at k-rate (this movement is interpolated internally to
eliminate "zipper noise" if sr not equal to kr).

  Syntax

aW, aX, aY, aZ spat3d ain, kX, kY, kZ, idist, ift, imode, imdel, iovr [, istor]

  Initialization

idist -- For modes 0 to 3, idist is the unit circle distance in meters.
For mode 4, idist is the distance between microphones.

The following formulas describe amplitude and delay as a function of
sound source distance from microphone(s):

amplitude = 1 / (0.1 + distance)

delay = distance / 340 (in seconds)

Distance can be calculated as:

distance = sqrt(iX^2 + iY^2 + iZ^2)

In Mode 4, distance can be calculated as:

distance from left mic = sqrt((iX + idist/2)^2 + iY^2 + iZ^2)
distance from right mic = sqrt((iX - idist/2)^2 + iY^2 + iZ^2)

With spat3d the distance between the sound source and any microphone
should be at least (340 * 18) / sr meters. Shorter distances will work,
but may produce artifacts in some cases. There is no such limitation for
spat3di and spat3dt.

Sudden changes or discontinuities in sound source location can result in
pops or clicks. Very fast movement may also degrade quality.

ift -- Function table storing room parameters (for free field
spatialization, set it to zero or negative). Table size is 54. The
values in the table are:

Room Parameter  Purpose
0       Early reflection recursion depth (0 is the sound source, 1 is the
first reflection etc.) for spat3d and spat3di. The number of echoes for
four walls (front, back, right, left) is: N = (2*R + 2) * R. If all six
walls are enabled: N = (((4*R + 6)*R + 8)*R) / 3
1       Late reflection recursion depth (used by spat3dt only). spat3dt skips
early reflections and renders echoes up to this level. If early
reflection depth is negative, spat3d and spat3di will output zero, while
spat3dt will start rendering from the sound source.
2       imdel for spat3d. Overrides opcode parameter if non-negative.
3       irlen for spat3dt. Overrides opcode parameter if non-negative.
4       idist value. Overrides opcode parameter if >= 0.
5       Random seed (0 - 65535) -1 seeds from current time.
6 - 53  wall parameters (w = 6: ceil, w = 14: floor, w = 22: front, w =
30: back, w = 38: right, w = 46: left)
w + 0   Enable reflections from this wall (0: no, 1: yes)
w + 1   Wall distance from listener (in meters)
w + 2   Randomization of wall distance (0 - 1) (in units of 1 / (wall
distance))
w + 3   Reflection level (-1 - 1)
w + 4   Parametric equalizer frequency in Hz.
w + 5   Parametric equalizer level (1.0: no filtering)
w + 6   Parametric equalizer Q (0.7071: no resonance)
w + 7   Parametric equalizer mode (0: peak EQ, 1: low shelf, 2: high shelf)

imode -- Output mode

  * 0: B format with W output only (mono)

===========================================================================
aout    =  aW                                                          *aout*

  * 1: B format with W and Y output (stereo)

===========================================================================
aleft   =  aW + 0.7071*aY                                             *aleft*
    aright  =  aW - 0.7071*aY

  * 2: B format with W, X, and Y output (2D). This can be converted to UHJ:

aWre, aWim      hilbert aW
    aXre, aXim      hilbert aX
    aYre, aYim      hilbert aY
    aWXr    =  0.0928*aXre + 0.4699*aWre
    aWXiYr  =  0.2550*aXim - 0.1710*aWim + 0.3277*aYre
    aleft   =  aWXr + aWXiYr
    aright  =  aWXr - aWXiYr

  * 3: B format with all outputs (3D)

  * 4: Simulates a pair of microphones (stereo output)

aW      butterlp aW, ifreq      ; recommended values for ifreq
    aY      butterlp aY, ifreq      ; are around 1000 Hz
    aleft   =  aW + aX
    aright  =  aY + aZ

Mode 0 is the cheapest to calculate, while mode 4 is the most expensive.

In Mode 4, The optional lowpass filters can change the frequency
response depending on direction. For example, if the sound source is
located left to the listener then the high frequencies are attenuated in
the right channel and slightly increased in the left. This effect can be
disabled by not using filters. You can also experiment with other
filters (tone etc.) for better effect.

Note that mode 4 is most useful for listening with headphones, and is
also more expensive to calculate than the B-format (0 to 3) modes. The
idist parameter in this case sets the distance between left and right
microphone; for headphones, values between 0.2 - 0.25 are recommended,
although higher settings up to 0.4 may be used for wide stereo effects.

More information about B format can be found here:
http://www.york.ac.uk/inst/mustech/3d_audio/ambis2.htm

imdel -- Maximum delay time for spat3d in seconds. This has to be longer
than the delay time of the latest reflection (depends on room
dimensions, sound source distance, and recursion depth; using this
formula gives a safe (although somewhat overestimated) value:

imdel = (R + 1) * sqrt(W*W + H*H + D*D) / 340.0

where R is the recursion depth, W, H, and D are the width, height, and
depth of the room, respectively).

iovr -- Oversample ratio for spat3d (1 to 8). Setting it higher improves
quality at the expense of memory and CPU usage. The recommended value is 2.

istor (optional, default=0) -- Skip initialization if non-zero (default:
0).

  Performance

aW, aX, aY, aZ -- Output signals

        mode 0  mode 1  mode 2  mode 3  mode 4
aW      W out   W out   W out   W out   left chn / low freq.
aX      0       0       X out   X out   left chn / high frq.
aY      0       Y out   Y out   Y out   right chn / low frq.
aZ      0       0       0       Z out   right chn / high fr.

ain -- Input signal

kX, kY, kZ -- Sound source coordinates (in meters)

If you encounter very slow performance (up to 100 times slower), it may
be caused by denormals (this is also true of many other IIR opcodes,
including butterlp, pareq, hilbert, and many others). Underflows can be
avoided by:

  * Using the denorm opcode on ain before spat3d.

  * mixing low level DC or noise to the input signal, e.g.

atmp rnd31 1/1e24, 0, 0

aW, aX, aY, aZ spa3di ain + atmp, ...

or

aW, aX, aY, aZ spa3di ain + 1/1e24, ...

  * reducing irlen in the case of spat3dt (which does not have an input
    signal). A value of about 0.005 is suitable for most uses, although
    it also depends on EQ settings. If the equalizer is not used,
    “irlen” can be set to 0.


===========================================================================
spat3di                                                             *spat3di*

  Description

This opcode positions the input sound in a 3D space, with optional
simulation of room acoustics, in various output formats. With spat3di,
sound source position is set at i-time.

  Syntax

aW, aX, aY, aZ spat3di ain, iX, iY, iZ, idist, ift, imode [, istor]

  Initialization

iX -- Sound source X coordinate in meters (positive: right, negative: left)

iY -- Sound source Y coordinate in meters (positive: front, negative: back)

iZ -- Sound source Z coordinate in meters (positive: up, negative: down)

idist -- For modes 0 to 3, idist is the unit circle distance in meters.
For mode 4, idist is the distance between microphones.

The following formulas describe amplitude and delay as a function of
sound source distance from microphone(s):

amplitude = 1 / (0.1 + distance)

delay = distance / 340 (in seconds)

Distance can be calculated as:

distance = sqrt(iX^2 + iY^2 + iZ^2)

In Mode 4, distance can be calculated as:

distance from left mic = sqrt((iX + idist/2)^2 + iY^2 + iZ^2)
distance from right mic = sqrt((iX - idist/2)^2 + iY^2 + iZ^2)

With spat3d the distance between the sound source and any microphone
should be at least (340 * 18) / sr meters. Shorter distances will work,
but may produce artifacts in some cases. There is no such limitation for
spat3di and spat3dt.

Sudden changes or discontinuities in sound source location can result in
pops or clicks. Very fast movement may also degrade quality.

ift -- Function table storing room parameters (for free field
spatialization, set it to zero or negative). Table size is 54. The
values in the table are:

Room Parameter  Purpose
0       Early reflection recursion depth (0 is the sound source, 1 is the
first reflection etc.) for spat3d and spat3di. The number of echoes for
four walls (front, back, right, left) is: N = (2*R + 2) * R. If all six
walls are enabled: N = (((4*R + 6)*R + 8)*R) / 3
1       Late reflection recursion depth (used by spat3dt only). spat3dt skips
early reflections and renders echoes up to this level. If early
reflection depth is negative, spat3d and spat3di will output zero, while
spat3dt will start rendering from the sound source.
2       imdel for spat3d. Overrides opcode parameter if non-negative.
3       irlen for spat3dt. Overrides opcode parameter if non-negative.
4       idist value. Overrides opcode parameter if >= 0.
5       Random seed (0 - 65535) -1 seeds from current time.
6 - 53  wall parameters (w = 6: ceil, w = 14: floor, w = 22: front, w =
30: back, w = 38: right, w = 46: left)
w + 0   Enable reflections from this wall (0: no, 1: yes)
w + 1   Wall distance from listener (in meters)
w + 2   Randomization of wall distance (0 - 1) (in units of 1 / (wall
distance))
w + 3   Reflection level (-1 - 1)
w + 4   Parametric equalizer frequency in Hz.
w + 5   Parametric equalizer level (1.0: no filtering)
w + 6   Parametric equalizer Q (0.7071: no resonance)
w + 7   Parametric equalizer mode (0: peak EQ, 1: low shelf, 2: high shelf)

imode -- Output mode

  * 0: B format with W output only (mono)

aout    =  aW

  * 1: B format with W and Y output (stereo)

aleft   =  aW + 0.7071*aY
aright  =  aW - 0.7071*aY

  * 2: B format with W, X, and Y output (2D). This can be converted to UHJ:

aWre, aWim      hilbert aW
    aXre, aXim      hilbert aX
    aYre, aYim      hilbert aY
    aWXr    =  0.0928*aXre + 0.4699*aWre
    aWXiYr  =  0.2550*aXim - 0.1710*aWim + 0.3277*aYre
    aleft   =  aWXr + aWXiYr
    aright  =  aWXr - aWXiYr

  * 3: B format with all outputs (3D)

  * 4: Simulates a pair of microphones (stereo output)

aW      butterlp aW, ifreq      ; recommended values for ifreq
aY      butterlp aY, ifreq      ; are around 1000 Hz
aleft   =  aW + aX
aright  =  aY + aZ

Mode 0 is the cheapest to calculate, while mode 4 is the most expensive.

In Mode 4, The optional lowpass filters can change the frequency
response depending on direction. For example, if the sound source is
located left to the listener then the high frequencies are attenuated in
the right channel and slightly increased in the left. This effect can be
disabled by not using filters. You can also experiment with other
filters (tone etc.) for better effect.

Note that mode 4 is most useful for listening with headphones, and is
also more expensive to calculate than the B-format (0 to 3) modes. The
idist parameter in this case sets the distance between left and right
microphone; for headphones, values between 0.2 - 0.25 are recommended,
although higher settings up to 0.4 may be used for wide stereo effects.

More information about B format can be found here:
http://www.york.ac.uk/inst/mustech/3d_audio/ambis2.htm

istor (optional, default=0) -- Skip initialization if non-zero (default:
0).

  Performance

ain -- Input signal

aW, aX, aY, aZ -- Output signals

        mode 0  mode 1  mode 2  mode 3  mode 4
aW      W out   W out   W out   W out   left chn / low freq.
aX      0       0       X out   X out   left chn / high frq.
aY      0       Y out   Y out   Y out   right chn / low frq.
aZ      0       0       0       Z out   right chn / high fr.

If you encounter very slow performance (up to 100 times slower), it may
be caused by denormals (this is also true of many other IIR opcodes,
including butterlp, pareq, hilbert, and many others). Underflows can be
avoided by:

  * Using the denorm opcode on ain before spat3di.

  * mixing low level DC or noise to the input signal, e.g.

atmp rnd31 1/1e24, 0, 0

aW, aX, aY, aZ spat3di ain + atmp, ...

or

aW, aX, aY, aZ spa3di ain + 1/1e24, ...

  * reducing irlen in the case of spat3dt (which does not have an input
    signal). A value of about 0.005 is suitable for most uses, although
    it also depends on EQ settings. If the equalizer is not used,
    “irlen” can be set to 0.


===========================================================================
spat3dt                                                             *spat3dt*

  Description

This opcode positions the input sound in a 3D space, with optional
simulation of room acoustics, in various output formats. spat3dt can be
used to render the impulse response at i-time, storing output in a
function table, suitable for convolution.

  Syntax

spat3dt ioutft, iX, iY, iZ, idist, ift, imode, irlen [, iftnocl]

  Initialization

ioutft -- Output ftable number for spat3dt. W, X, Y, and Z outputs are
written interleaved to this table. If the table is too short, output
will be truncated.

iX -- Sound source X coordinate in meters (positive: right, negative: left)

iY -- Sound source Y coordinate in meters (positive: front, negative: back)

iZ -- Sound source Z coordinate in meters (positive: up, negative: down)

idist -- For modes 0 to 3, idist is the unit circle distance in meters.
For mode 4, idist is the distance between microphones.

The following formulas describe amplitude and delay as a function of
sound source distance from microphone(s):

amplitude = 1 / (0.1 + distance)

delay = distance / 340 (in seconds)

Distance can be calculated as:

distance = sqrt(iX^2 + iY^2 + iZ^2)

In Mode 4, distance can be calculated as:

distance from left mic = sqrt((iX + idist/2)^2 + iY^2 + iZ^2)
distance from right mic = sqrt((iX - idist/2)^2 + iY^2 + iZ^2)

With spat3d the distance between the sound source and any microphone
should be at least (340 * 18) / sr meters. Shorter distances will work,
but may produce artifacts in some cases. There is no such limitation for
spat3di and spat3dt.

Sudden changes or discontinuities in sound source location can result in
pops or clicks. Very fast movement may also degrade quality.

ift -- Function table storing room parameters (for free field
spatialization, set it to zero or negative). Table size is 54. The
values in the table are:

Room Parameter  Purpose
0       Early reflection recursion depth (0 is the sound source, 1 is the
first reflection etc.) for spat3d and spat3di. The number of echoes for
four walls (front, back, right, left) is: N = (2*R + 2) * R. If all six
walls are enabled: N = (((4*R + 6)*R + 8)*R) / 3
1       Late reflection recursion depth (used by spat3dt only). spat3dt skips
early reflections and renders echoes up to this level. If early
reflection depth is negative, spat3d and spat3di will output zero, while
spat3dt will start rendering from the sound source.
2       imdel for spat3d. Overrides opcode parameter if non-negative.
3       irlen for spat3dt. Overrides opcode parameter if non-negative.
4       idist value. Overrides opcode parameter if >= 0.
5       Random seed (0 - 65535) -1 seeds from current time.
6 - 53  wall parameters (w = 6: ceil, w = 14: floor, w = 22: front, w =
30: back, w = 38: right, w = 46: left)
w + 0   Enable reflections from this wall (0: no, 1: yes)
w + 1   Wall distance from listener (in meters)
w + 2   Randomization of wall distance (0 - 1) (in units of 1 / (wall
distance))
w + 3   Reflection level (-1 - 1)
w + 4   Parametric equalizer frequency in Hz.
w + 5   Parametric equalizer level (1.0: no filtering)
w + 6   Parametric equalizer Q (0.7071: no resonance)
w + 7   Parametric equalizer mode (0: peak EQ, 1: low shelf, 2: high shelf)

imode -- Output mode

  * 0: B format with W output only (mono)

aout    =  aW

  * 1: B format with W and Y output (stereo)

aleft   =  aW + 0.7071*aY
aright  =  aW - 0.7071*aY

  * 2: B format with W, X, and Y output (2D). This can be converted to UHJ:

aWre, aWim      hilbert aW
aXre, aXim      hilbert aX
aYre, aYim      hilbert aY
aWXr    =  0.0928*aXre + 0.4699*aWre
aWXiYr  =  0.2550*aXim - 0.1710*aWim + 0.3277*aYre
aleft   =  aWXr + aWXiYr
aright  =  aWXr - aWXiYr

  * 3: B format with all outputs (3D)

  * 4: Simulates a pair of microphones (stereo output)

aW      butterlp aW, ifreq      ; recommended values for ifreq
aY      butterlp aY, ifreq      ; are around 1000 Hz
aleft   =  aW + aX
aright  =  aY + aZ

Mode 0 is the cheapest to calculate, while mode 4 is the most expensive.

In Mode 4, The optional lowpass filters can change the frequency
response depending on direction. For example, if the sound source is
located left to the listener then the high frequencies are attenuated in
the right channel and slightly increased in the left. This effect can be
disabled by not using filters. You can also experiment with other
filters (tone etc.) for better effect.

Note that mode 4 is most useful for listening with headphones, and is
also more expensive to calculate than the B-format (0 to 3) modes. The
idist parameter in this case sets the distance between left and right
microphone; for headphones, values between 0.2 - 0.25 are recommended,
although higher settings up to 0.4 may be used for wide stereo effects.

More information about B format can be found here:
http://www.york.ac.uk/inst/mustech/3d_audio/ambis2.htm

irlen -- Impulse response length of echoes (in seconds). Depending on
filter parameters, values around 0.005-0.01 are suitable for most uses
(higher values result in more accurate output, but slower rendering)

iftnocl (optional, default=0) -- Do not clear output ftable (mix to
existing data) if set to 1, clear table before writing if set to 0
(default: 0).


===========================================================================
spdist                                                               *spdist*

  Description

spdist uses the same xy data as space, also either from a text file
using Gen28 or from x and y arguments given to the unit directly. The
purpose of this unit is to make available the values for distance that
are calculated from the xy coordinates.

In the case of space, the xy values are used to determine a distance
which is used to attenuate the signal and prepare it for use in spsend.
But it is also useful to have these values for distance available to
scale the frequency of the signal before it is sent to the space unit.

  Syntax

k1 spdist ifn, ktime, kx, ky

  Initialization

ifn -- number of the stored function created using Gen28. This function
generator reads a text file which contains sets of three values
representing the xy coordinates and a time-tag for when the signal
should be placed at that location. The file should look like:

  0       -1       1
  1        1       1
  2        4       4
  2.1     -4      -4
  3       10     -10
  5      -40       0

If that file were named "move" then the Gen28 call in the score would like:

  f1 0 0 28 "move"

Gen28 takes 0 as the size and automatically allocates memory. It creates
values to 10 milliseconds of resolution. So in this case there will be
500 values created by interpolating X1 to X2 to X3 and so on, and Y1 to
Y2 to Y3 and so on, over the appropriate number of values that are
stored in the function table. In the above example, the sound will begin
in the left front, over 1 second it will move to the right front, over
another second it move further into the distance but still in the right
front, then in just 1/10th of a second it moves to the left rear, a bit
distant. Finally over the last .9 seconds the sound will move to the
right rear, moderately distant, and it comes to rest between the two
left channels (due west!), quite distant. Since the values in the table
are accessed through the use of a time-pointer in the space unit, the
actual timing can be made to follow the file's timing exactly or it can
be made to go faster or slower through the same trajectory. If you have
access to the GUI that allows one to draw and edit the files, there is
no need to create the text files manually. But as long as the file is
ASCII and in the format shown above, it doesn't matter how it is made!

IMPORTANT: If ifn is 0 then spdist will take its values for the xy
coordinates from kx and ky.

  Performance

The configuration of the xy coordinates in space places the signal in
the following way:

  * a1 is -1, 1

  * a2 is 1, 1

  * a3 is -1, -1

  * a4 is 1, -1

This assumes a loudspeaker set up as a1 is left front, a2 is right
front, a3 is left back, a4 is right back. Values greater than 1 will
result in sounds being attenuated, as if in the distance. space
considers the speakers to be at a distance of 1; smaller values of xy
can be used, but space will not amplify the signal in this case. It
will, however balance the signal so that it can sound as if it were
within the 4 speaker space. x=0, y=1, will place the signal equally
balanced between left and right front channels, x=y=0 will place the
signal equally in all 4 channels, and so on. Although there must be 4
output signals from space, it can be used in a 2 channel orchestra. If
the xy's are kept so that Y>=1, it should work well to do panning and
fixed localization in a stereo field.

ktime -- index into the table containing the xy coordinates. If used like:

  ktime           line  0, 5, 5
  a1, a2, a3, a4  space asig, 1, ktime, ...

with the file "move" described above, the speed of the signal's movement
will be exactly as described in that file. However:

  ktime           line  0, 10, 5

the signal will move at half the speed specified. Or in the case of:

  ktime           line  5, 15, 0

the signal will move in the reverse direction as specified and 3 times
slower! Finally:

  ktime           line  2, 10, 3

will cause the signal to move only from the place specified in line 3 of
the text file to the place specified in line 5 of the text file, and it
will take 10 seconds to do it.

kx, ky -- when ifn is 0, space and spdist will use these values as the
XY coordinates to localize the signal.


===========================================================================
specaddm                                                           *specaddm*

  Description

Perform a weighted add of two input spectra.

  Syntax

wsig specaddm wsig1, wsig2 [, imul2]

  Initialization

imul2 (optional, default=0) -- if non-zero, scale the wsig2 magnitudes
before adding. The default value is 0.

  Performance

wsig1 -- the first input spectra.

wsig2 -- the second input spectra.

Do a weighted add of two input spectra. For each channel of the two
input spectra, the two magnitudes are combined and written to the output
according to:

magout = mag1in + mag2in * imul2

The operation is performed whenever the input wsig1 is sensed to be new.
This unit will (at Initialization) verify the consistency of the two
spectra (equal size, equal period, equal mag types).


===========================================================================
specdiff                                                           *specdiff*

  Description

Finds the positive difference values between consecutive spectral frames.

  Syntax

wsig specdiff wsigin

  Performance

wsig -- the output spectrum.

wsigin -- the input spectra.

Finds the positive difference values between consecutive spectral
frames. At each new frame of wsigin, each magnitude value is compared
with its predecessor, and the positive changes written to the output
spectrum. This unit is useful as an energy onset detector.


===========================================================================
specdisp                                                           *specdisp*

  Description

Displays the magnitude values of the spectrum.

  Syntax

specdisp wsig, iprd [, iwtflg]

  Initialization

iprd -- the period, in seconds, of each new display.

iwtflg (optional, default=0) -- wait flag. If non-zero, hold each
display until released by the user. The default value is 0 (no wait).

  Performance

wsig -- the input spectrum.

Displays the magnitude values of spectrum wsig every iprd seconds
(rounded to some integral number of wsig's originating iprd).


===========================================================================
specfilt                                                           *specfilt*

  Description

Filters each channel of an input spectrum.

  Syntax

wsig specfilt wsigin, ifhtim

  Initialization

ifhtim -- half-time constant.

  Performance

wsigin -- the input spectrum.

Filters each channel of an input spectrum. At each new frame of wsigin,
each magnitude value is injected into a 1st-order lowpass recursive
filter, whose half-time constant has been initially set by sampling the
ftable ifhtim across the (logarithmic) frequency space of the input
spectrum. This unit effectively applies a persistence factor to the data
occurring in each spectral channel, and is useful for simulating the
energy integration that occurs during auditory perception. It may also
be used as a time-attenuated running histogram of the spectral
distribution.


===========================================================================
spechist                                                           *spechist*

  Description

Accumulates the values of successive spectral frames.

  Syntax

wsig spechist wsigin

  Performance

wsigin -- the input spectra.

Accumulates the values of successive spectral frames. At each new frame
of wsigin, the accumulations-to-date in each magnitude track are written
to the output spectrum. This unit thus provides a running histogram of
spectral distribution.


===========================================================================
specptrk                                                           *specptrk*

  Description

Estimate the pitch of the most prominent complex tone in the spectrum.

  Syntax

koct, kamp specptrk wsig, kvar, ilo, ihi, istr, idbthresh, inptls, \
      irolloff [, iodd] [, iconfs] [, interp] [, ifprd] [, iwtflg]

  Initialization

ilo, ihi, istr -- pitch range conditioners (low, high, and starting)
expressed in decimal octave form.

idbthresh -- energy threshold (in decibels) for pitch tracking to occur.
Once begun, tracking will be continuous until the energy falls below one
half the threshold (6 dB down), whence the koct and kamp outputs will be
zero until the full threshold is again surpassed. idbthresh is a guiding
value. At initialization it is first converted to the idbout mode of the
source spectrum (and the 6 dB down point becomes .5, .25, or 1/root 2
for modes 0, 2 and 3). The values are also further scaled to allow for
the weighted partial summation used during correlation.The actual
thresholding is done using the internal weighted and summed kamp value
that is visible as the second output parameter.

inptls, irolloff -- number of harmonic partials used as a matching
template in the spectrally-based pitch detection, and an amplitude
rolloff for the set expressed as some fraction per octave (linear, so
don't roll off to negative). Since the partials and rolloff fraction can
affect the pitch following, some experimentation will be useful: try 4
or 5 partials with .6 rolloff as an initial setting; raise to 10 or 12
partials with rolloff .75 for complex timbres like the bassoon (weak
fundamental). Computation time is dependent on the number of partials
sought. The maximum number is 16.

iodd (optional) -- if non-zero, employ only odd partials in the above
set (e.g. inptls of 4 would employ partials 1,3,5,7). This improves the
tracking of some instruments like the clarinet The default value is 0
(employ all partials).

iconfs (optional) -- number of confirmations required for the pitch
tracker to jump an octave, pro-rated for fractions of an octave (i.e.
the value 12 implies a semitone change needs 1 confirmation (two hits)
at the spectrum generating iprd). This parameter limits spurious pitch
analyses such as octave errors. A value of 0 means no confirmations
required; the default value is 10.

interp (optional) -- if non-zero, interpolate each output signal (koct,
kamp) between incoming wsig frames. The default value is 0 (repeat the
signal values between frames).

ifprd (optional) -- if non-zero, display the internally computed
spectrum of candidate fundamentals. The default value is 0 (no display).

iwtftg (optional) -- wait flag. If non-zero, hold each display until
released by the user. The default value is 0 (no wait).

  Performance

At note initialization this unit creates a template of inptls
harmonically related partials (odd partials, if iodd non-zero) with
amplitude rolloff to the fraction irolloff per octave. At each new frame
of wsig, the spectrum is cross-correlated with this template to provide
an internal spectrum of candidate fundamentals (optionally displayed). A
likely pitch/amp pair (koct, kamp, in decimal octave and summed idbout
form) is then estimated. koct varies from the previous koct by no more
than plus or minus kvar decimal octave units. It is also guaranteed to
lie within the hard limit range ilo -- ihi (decimal octave low and high
pitch). kvar can be dynamic, e.g. onset amp dependent. Pitch resolution
uses the originating spectrum ifrqs bins/octave, with further parabolic
interpolation between adjacent bins. Settings of root magnitude, ifrqs =
24, iq = 15 should capture all the inflections of interest. Between
frames, the output is either repeated or interpolated at the k-rate.
(See spectrum.)


===========================================================================
specscal                                                           *specscal*

  Description

Scales an input spectral datablock with spectral envelopes.

  Syntax

wsig specscal wsigin, ifscale, ifthresh

  Initialization

ifscale -- scale function table. A function table containing values by
which a value's magnitude is rescaled.

ifthresh -- threshold function table. If ifthresh is non-zero, each
magnitude is reduced by its corresponding table-value (to not less than
zero)

  Performance

wsig -- the output spectrum

wsigin -- the input spectra

Scales an input spectral datablock with spectral envelopes. Function
tables ifthresh and ifscale are initially sampled across the
(logarithmic) frequency space of the input spectrum; then each time a
new input spectrum is sensed the sampled values are used to scale each
of its magnitude channels as follows: if ifthresh is non-zero, each
magnitude is reduced by its corresponding table-value (to not less than
zero); then each magnitude is rescaled by the corresponding ifscale
value, and the resulting spectrum written to wsig.


===========================================================================
specsum                                                             *specsum*

  Description

Sums the magnitudes across all channels of the spectrum.

  Syntax

ksum specsum wsig [, interp]

  Initialization

interp (optional, default-0) -- if non-zero, interpolate the output
signal (koct or ksum). The default value is 0 (repeat the signal value
between changes).

  Performance

ksum -- the output signal.

wsig -- the input spectrum.

Sums the magnitudes across all channels of the spectrum. At each new
frame of wsig, the magnitudes are summed and released as a scalar ksum
signal. Between frames, the output is either repeated or interpolated at
the k-rate. This unit produces a k-signal summation of the magnitudes
present in the spectral data, and is thereby a running measure of its
moment-to-moment overall strength.


===========================================================================
spectrum                                                           *spectrum*

  Description

Generate a constant-Q, exponentially-spaced DFT across all octaves of a
multiply-downsampled control or audio input signal.

  Syntax

wsig spectrum xsig, iprd, iocts, ifrqa [, iq] [, ihann] [, idbout] \
      [, idsprd] [, idsinrs]

  Initialization

ihann (optional) -- apply a Hamming or Hanning window to the input. The
default is 0 (Hamming window)

idbout (optional) -- coded conversion of the DFT output:

  * 0 = magnitude

  * 1 = dB

  * 2 = mag squared

  * 3 = root magnitude

The default value is 0 (magnitude).

idisprd (optional) -- if non-zero, display the composite downsampling
buffer every idisprd seconds. The default value is 0 (no display).

idsines (optional) -- if non-zero, display the Hamming or Hanning
windowed sinusoids used in DFT filtering. The default value is 0 (no
sinusoid display).

  Performance

This unit first puts signal asig or ksig through iocts of successive
octave decimation and downsampling, and preserves a buffer of
down-sampled values in each octave (optionally displayed as a composite
buffer every idisprd seconds). Then at every iprd seconds, the preserved
samples are passed through a filter bank (ifrqs parallel filters per
octave, exponentially spaced, with frequency/bandwidth Q of iq), and the
output magnitudes optionally converted (idbout ) to produce a
band-limited spectrum that can be read by other units.

The stages in this process are computationally intensive, and
computation time varies directly with iocts, ifrqs, iq, and inversely
with iprd. Settings of ifrqs = 12, iq = 10, idbout = 3, and iprd = .02
will normally be adequate, but experimentation is encouraged. ifrqs
currently has a maximum of 120 divisions per octave. For audio input,
the frequency bins are tuned to coincide with A440.

This unit produces a self-defining spectral datablock wsig, whose
characteristics used (iprd, iocts, ifrqs, idbout) are passed via the
data block itself to all derivative wsigs. There can be any number of
spectrum units in an instrument or orchestra, but all wsig names must be
unique.


===========================================================================
splitrig                                                           *splitrig*

  Description

splitrig splits a trigger signal (i.e. a timed sequence of control-rate
impulses) into several channels following a structure designed by the user.

  Syntax

splitrig ktrig, kndx, imaxtics, ifn, kout1 [,kout2,...,koutN]

  Initialization

imaxtics - number of tics belonging to largest pattern

ifn - number of table containing channel-data structuring

  Performance

asig - incoming (input) signal

ktrig - trigger signal

The splitrig opcode splits a trigger signal into several output channels
according to one or more patterns provided by the user. Normally the
regular timed trigger signal generated by metro opcode is used to be
transformed into rhythmic pattern that can trig several independent
melodies or percussion riffs. But you can also start from non-isocronous
trigger signals. This allows to use some "interpretative" and less
"mechanic" groove variations. Patterns are looped and each
numtics_of_pattern_N the cycle is repeated.

The scheme of patterns is defined by the user and is stored into ifn
table according to the following format:

gi1  ftgen 1,0,1024,  -2 \  ; table is generated with GEN02 in this case
\                           ;
numtics_of_pattern_1, \ ;pattern 1
   tic1_out1, tic1_out2, ... , tic1_outN,\
   tic2_out1, tic2_out2, ... , tic2_outN,\
   tic3_out1, tic3_out2, ... , tic3_outN,\
   .....
   ticN_out1, ticN_out2, ... , ticN_outN,\
\
numtics_of_pattern_2, \ ;pattern 2
   tic1_out1, tic1_out2, ... , tic1_outN,\
   tic2_out1, tic2_out2, ... , tic2_outN,\
   tic3_out1, tic3_out2, ... , tic3_outN,\
   .....
   ticN_out1, ticN_out2, ... , ticN_outN,\
   .....
\
numtics_of_pattern_N,\ ;pattern N
   tic1_out1, tic1_out2, ... , tic1_outN,\
   tic2_out1, tic2_out2, ... , tic2_outN,\
   tic3_out1, tic3_out2, ... , tic3_outN,\
   .....
   ticN_out1, ticN_out2, ... , ticN_outN,\

This scheme can contain more than one pattern, each one with a different
number of rows. Each pattern is preceded by a a special row containing a
single numtics_of_pattern_N field; this field expresses the number of
tics that makes up the corresponding pattern. Each pattern's row makes
up a tic. Each pattern's column corresponds to a channel, and each field
of a row is a number that makes up the value outputted by the
corresponding koutXX channel (if number is a zero, corresponding output
channel will not trigger anything in that particular arguments).
Obviously, all rows must contain the same number of fields that must be
equal to the number of koutXX channel. All patterns must contain the
same number of rows, this number must be equal to the largest pattern
and is defined by imaxtics variable. Even if a pattern has less tics
than the largest pattern, it must be made up of the same number of rows,
in this case, some of these rows, at the end of the pattern itself, will
not be used (and can be set to any value, because it doesn't matter).

The kndx variable chooses the number of the pattern to be played, zero
indicating the first pattern. Each time the integer part of kndx
changes, tic counter is reset to zero.

Patterns are looped and each numtics_of_pattern_N the cycle is repeated.

examples 4 - calculate average value of asig in the time interval

This opcode can be useful in several situations, for example to
implement a vu-meter


===========================================================================
sprintf                                                             *sprintf*

  Description

sprintf write printf-style formatted output to a string variable,
similarly to the C function sprintf(). sprintf runs at i-time only.

  Syntax

Sdst sprintf Sfmt, xarg1[, xarg2[, ... ]]

  Initialization

Sfmt -- format string, has the same format as in printf() and other
similar C functions, except length modifiers (l, ll, h, etc.) are not
supported. The following conversion specifiers are allowed:

  * d, i, o, u, x, X, e, E, f, F, g, G, c, s

xarg1, xarg2, ... -- input arguments (max. 30) for format, should be
i-rate for all conversion specifiers except %s, which requires a string
argument. Integer formats like %d round the input values to the nearest
integer.

  Performance

Sdst -- output string variable


===========================================================================
sprintfk                                                           *sprintfk*

  Description

sprintfk writes printf-style formatted output to a string variable,
similarly to the C function sprintf(). sprintfk runs both at
initialization and performance time.

  Syntax

Sdst sprintfk Sfmt, xarg1[, xarg2[, ... ]]

  Initialization

Sfmt -- format string, has the same format as in printf() and other
similar C functions, except length modifiers (l, ll, h, etc.) are not
supported. The following conversion specifiers are allowed:

  * d, i, o, u, x, X, e, E, f, F, g, G, c, s

xarg1, xarg2, ... -- input arguments (max. 30) for format, should be
i-rate for all conversion specifiers except %s, which requires a string
argument. sprintfk also allows k-rate number arguments, but these should
still be valid at init time as well (unless sprintfk is skipped with
igoto). Integer formats like %d round the input values to the nearest
integer.

  Performance

Sdst -- output string variable


===========================================================================
spsend                                                               *spsend*

  Description

spsend depends upon the existence of a previously defined space. The
output signals from spsend are derived from the values given for xy and
reverb in the space and are ready to be sent to local or global reverb
units (see example below).

  Syntax

a1, a2, a3, a4 spsend

  Performance

The configuration of the xy coordinates in space places the signal in
the following way:

  * a1 is -1, 1

  * a2 is 1, 1

  * a3 is -1, -1

  * a4 is 1, -1

This assumes a loudspeaker set up as a1 is left front, a2 is right
front, a3 is left back, a4 is right back. Values greater than 1 will
result in sounds being attenuated, as if in the distance. space
considers the speakers to be at a distance of 1; smaller values of xy
can be used, but space will not amplify the signal in this case. It
will, however balance the signal so that it can sound as if it were
within the 4 speaker space. x=0, y=1, will place the signal equally
balanced between left and right front channels, x=y=0 will place the
signal equally in all 4 channels, and so on. Although there must be 4
output signals from space, it can be used in a 2 channel orchestra. If
the xy's are kept so that Y>=1, it should work well to do panning and
fixed localization in a stereo field.


===========================================================================
sqrt                                                                   *sqrt*

  Description

Returns the square root of x (x non-negative).

The argument value is restricted for log, log10, and sqrt.

  Syntax

sqrt(x) (no rate restriction)

where the argument within the parentheses may be an expression. Value
converters perform arithmetic translation from units of one kind to
units of another. The result can then be a term in a further expression.


===========================================================================
sr                                                                       *sr*

  Description

These statements are global value assignments, made at the beginning of
an orchestra, before any instrument block is defined. Their function is
to set certain reserved symbol variables that are required for
performance. Once set, these reserved symbols can be used in expressions
anywhere in the orchestra.

  Syntax

sr = iarg

  Initialization

sr = (optional) -- set sampling rate to iarg samples per second per
channel. The default value is 44100.

In addition, any global variable can be initialized by an init-time
assignment anywhere before the first instr statement. All of the above
assignments are run as instrument 0 (i-pass only) at the start of real
performance.

Beginning with Csound version 3.46, sr may be omitted. The sample rate
will be calculated from kr and ksmps, but this must evaluate to an
integer. If none of these global values is defined, the sample rate will
default to 44100. You will usually want to use a value that your
soundcard supports, like 44100 or 48000, otherwise, the audio generated
by csound may be unplayable, or you will get an error if you attempt to
run in real-time. You may naturally use a sample rate like 96000, for
off-line rendering even if your soundcard doesn't support it. Csound
will generate a valid file that can be played on capable systems.


===========================================================================
statevar                                                           *statevar*

  Description

Statevar is a new digital implementation of the analogue state-variable
filter. This filter has four simultaneous outputs: high-pass, low-pass,
band-pass and band-reject. This filter uses oversampling for sharper
resonance (default: 3 times oversampling). It includes a resonance
limiter that prevents the filter from getting unstable.

  Syntax

ahp,alp,abp,abr statevar ain, xcf, xq [, iosamps, istor]

  Initialization

iosamps -- number of times of oversampling used in the filtering
process. This will determine the maximum sharpness of the filter
resonance (Q). More oversampling allows higher Qs, less oversampling
will limit the resonance. The default is 3 times (iosamps=0).

istor --initial disposition of internal data space. Since filtering
incorporates a feedback loop of previous output, the initial status of
the storage space used is significant. A zero value will clear the
space; a non-zero value will allow previous information to remain. The
default value is 0.

  Performance

ahp -- high-pass output signal.

alp -- low-pass output signal.

abp -- band-pass signal.

abr -- band-reject signal.

asig -- input signal.

xcf -- filter cutoff frequency (k-rate or a-rate).

xq -- filter Q (k-rate or a-rate). This value is limited internally
depending on the frequency and the number of times of oversampling used
in the process (3-times oversampling by default).


===========================================================================
stix                                                                   *stix*

  Description

stix is a semi-physical model of a stick sound. It is one of the PhISEM
percussion opcodes. PhISEM (Physically Informed Stochastic Event
Modeling) is an algorithmic approach for simulating collisions of
multiple independent sound producing objects.

  Syntax

ares stix iamp, idettack [, inum] [, idamp] [, imaxshake]

  Initialization

iamp -- Amplitude of output. Note: As these instruments are stochastic,
this is only a approximation.

idettack -- period of time over which all sound is stopped

inum (optional) -- The number of beads, teeth, bells, timbrels, etc. If
zero, the default value is 30.

idamp (optional) -- the damping factor, as part of this equation:

damping_amount = 0.998 + (idamp * 0.002)

The default damping_amount is 0.998 which means that the default value
of idamp is 0. The maximum damping_amount is 1.0 (no damping). This
means the maximum value for idamp is 1.0.

The recommended range for idamp is usually below 75% of the maximum value.

imaxshake (optional) -- amount of energy to add back into the system.
The value should be in range 0 to 1.


===========================================================================
STKBandedWG                                                     *STKBandedWG*

  Description

This opcode uses banded waveguide techniques to model a variety of
sounds, including bowed bars, glasses, and bowls.

  Syntax

asignal STKBandedWG ifrequency, iamplitude, [kpress, kv1[, kmot, kv2[, klfo, kv3[, klfodepth, kv4[, kvel, kv5[, kstrk, kv6[, kinstr, kv7]]]]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

kpress -- controller 2, pressure of bow. Value range of kv1 is 0-127.

kmot -- controller 4, motion of bow. Value range of kv2 is 0-127.

klfo -- controller 11, speed of low-frequency oscillator. Value range of
kv3 is 0-127.

klfodepth -- controller 1, depth of low-frequency oscillator. Value
range of kv4 is 0-127.

kvel -- controller 128, velocity of bow. Value range of kv5 is 0-127.

kstrk -- controller 64, striking of bow. Value range of kv6 is 0-127.

kinstr -- controller 16, instrument presets (0 = uniform bar, 1 = tuned
bar, 2 = glass harmonica, 3 = Tibetan bowl). Value range of kv7 is 0-3.

  Notes

The code for this opcode is taken directly from the BandedWG class in
the Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More
on the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKBeeThree                                                     *STKBeeThree*

  Description

STK Hammond-oid organ-like FM synthesis instrument.

This opcode a simple 4 operator topology, also referred to as algorithm
8 of the TX81Z. It simulates the sound of a Hammond-oid organ, and some
related sounds.

  Syntax

asignal STKBeeThree ifrequency, iamplitude, [kop4, kv1[, kop3, kv2[, klfo, kv3[, klfodepth, kv4[, kadsr, kv5]]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

kop4 -- controller 2, gain of feedback of operator 4. Value range of kv1
is 0-127.

kop3 -- controller 4, gain of operator 3. Value range of kv2 is 0-127.

klfo -- controller 11, speed of low-frequency oscillator. Value range of
kv3 is 0-127.

klfodepth -- controller 1, depth of low-frequency oscillator. Value
range of kv4 is 0-127.

kadsr -- controller 128, ADSR 2 and 4 target. Value range of kv5 is 0-127.

  Notes

The code for this opcode is taken directly from the BeeThree class in
the Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More
on the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKBlowBotl                                                     *STKBlowBotl*

  Description

This opcode implements a helmholtz resonator (biquad filter) with a
polynomial jet excitation (a la Cook).

  Syntax

asignal STKBlowBotl ifrequency, iamplitude, [knoise, kv1[, klfo, kv2[, klfodepth, kv3[, kvol, kv4]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

knoise -- controller 4, gain of noise. Value range of kv1 is 0-127.

klfo -- controller 11, speed of low-frequency oscillator. Value range of
kv2 is 0-127.

klfodepth -- controller 1, depth of low-frequency oscillator. Value
range of kv3 is 0-127.

kvol -- controller 128, volume. Value range of kv4 is 0-127.

  Notes

The code for this opcode is taken directly from the BlowBotl class in
the Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More
on the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKBlowHole                                                     *STKBlowHole*

  Description

This opcode is based on the clarinet model, with the addition of a
two-port register hole and a three-port dynamic tonehole implementation.

In this implementation, the distances between the reed/register hole and
tonehole/bell are fixed. As a result, both the tonehole and register
hole will have variable influence on the playing frequency, which is
dependent on the length of the air column. In addition, the highest
playing freqeuency is limited by these fixed lengths.

  Syntax

asignal STKBlowHole ifrequency, iamplitude, [kreed, kv1[, knoise, kv2[, khole, kv3[, kreg, kv4[, kbreath, kv5]]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

kreed -- controller 2, stiffness of reed. Value range of kv1 is 0-127.

knoise -- controller 4, gain of noise. Value range of kv2 is 0-127.

khole -- controller 11, state of tonehole. Value range of kv3 is 0-127.

kreg -- controller 1, state of register. Value range of kv4 is 0-127.

kbreath -- controller 128, breath pressure. Value range of kv5 is 0-127.

  Notes

The code for this opcode is taken directly from the BlowHole class in
the Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More
on the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKBowed                                                           *STKBowed*

  Description

STKBowed is a bowed string instrument, using a waveguide model.

  Syntax

asignal STKBowed ifrequency, iamplitude, [kpress, kv1[, kpos, kv2[, klfo, kv3[, klfodepth, kv4[, kvol, kv5]]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

kpress -- controller 2, bow pressure. Value range of kv1 is 0-127.

kpos -- controller 4, position on bow. Value range of kv2 is 0-127.

klfo -- controller 11, speed of low-frequency oscillator. Value range of
kv3 is 0-127.

klfodepth -- controller 1, depth of low-frequency oscillator. Value
range of kv4 is 0-127.

kvol -- controller 128, volume. Value range of kv5 is 0-127.

  Note

The code for this opcode is taken directly from the Bowed class in the
Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More on
the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKBrass                                                           *STKBrass*

  Description

STKBrass uses a simple brass instrument waveguide model, a la Cook.

  Syntax

asignal STKBrass ifrequency, iamplitude, [klip, kv1[, kslide, kv2[, klfo, kv3[, klfodepth, kv4[, kvol, kv5]]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

klip -- controller 2, lip tension. Value range of kv1 is 0-127.

kslide -- controller 4, slide length. Value range of kv2 is 0-127.

klfo -- controller 11, speed of low-frequency oscillator. Value range of
kv3 is 0-127.

klfodepth -- controller 1, depth of low-frequency oscillator. Value
range of kv4 is 0-127.

kvol -- controller 128, volume. Value range of kv5 is 0-127.

  Note

The code for this opcode is taken directly from the Brass class in the
Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More on
the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKClarinet                                                     *STKClarinet*

  Description

STKClarinet uses a simple clarinet physical model.

  Syntax

asignal STKClarinet ifrequency, iamplitude, [kstiff, kv1[, knoise, kv2[, klfo, kv3[, klfodepth, kv4[, kbreath, kv5]]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

kstiff -- controller 2, reed stiffness. Value range of kv1 is 0-127.

knoise -- controller 4, gain of noise. Value range of kv2 is 0-127.

klfo -- controller 11, speed of low-frequency oscillator. Value range of
kv3 is 0-127.

klfodepth -- controller 1, depth of low-frequency oscillator. Value
range of kv4 is 0-127.

kbreath -- controller 128, breath pressure. Value range of kv5 is 0-127.

  Note

The code for this opcode is taken directly from the Clarinet class in
the Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More
on the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKDrummer                                                       *STKDrummer*

  Description

STKDrummer is a drum sampling synthesizer using raw waves and one-pole
filters, The drum rawwave files are sampled at 22050 Hz, but will be
appropriately interpolated for other sample rates.

  Syntax

asignal STKDrummer ifrequency, iamplitude

  Initialization

ifrequency -- Samples being played.

iamplitude -- Amplitude of note played (range 0-1).

  Note

The code for this opcode is taken directly from the Drummer class in the
Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More on
the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html


===========================================================================
STKFlute                                                           *STKFlute*

  Description

STKFlute uses a simple flute physical model. The jet model uses a
polynomial, a la Cook.

  Syntax

asignal STKFlute ifrequency, iamplitude, [kjet, kv1[, knoise, kv2[, klfo, kv3[, klfodepth, kv4[, kbreath, kv5]]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

kjet -- controller 2, jet delay. Value range of kv1 is 0-127.

knoise -- controller 4, gain of noise. Value range of kv2 is 0-127.

klfo -- controller 11, speed of low-frequency oscillator. Value range of
kv3 is 0-127.

klfodepth -- controller 1, depth of low-frequency oscillator. Value
range of kv4 is 0-127.

kbreath -- controller 128, breath pressure. Value range of kv5 is 0-127.

  Note

The code for this opcode is taken directly from the Flute class in the
Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More on
the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKFMVoices                                                     *STKFMVoices*

  Description

STKFMVoices is a singing FM synthesis instrument. It has 3 carriers and
a common modulator, also referred to as algorithm 6 of the TX81Z.

  Syntax

asignal STKFMVoices ifrequency, iamplitude, [kvowel, kv1[, kspec, kv2[, klfo, kv3[, klfodepth, kv4[, kadsr, kv5]]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

kvowel -- controller 2, vowel. Value range of kv1 is 0-127.

kspec -- controller 4, spectral tilt. Value range of kv2 is 0-127.

klfo -- controller 11, speed of low-frequency oscillator. Value range of
kv3 is 0-127.

klfodepth -- controller 1, depth of low-frequency oscillator. Value
range of kv4 is 0-127.

kadsr -- controller 128, ADSR 2 and 4 Target. Value range of kv5 is 0-127.

  Note

The code for this opcode is taken directly from the FMVoices class in
the Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More
on the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKHevyMetl                                                     *STKHevyMetl*

  Description

STKHevyMetl produces metal sounds, using FM synthesis. It uses 3 cascade
operators with feedback modulation, also referred to as algorithm 3 of
the TX81Z.

  Syntax

asignal STKHevyMetl ifrequency, iamplitude, [kmod, kv1[, kcross, kv2[, klfo, kv3[, klfodepth, kv4[, kadsr, kv5]]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

kmod -- controller2, total modulator index. Value range of kv1 is 0-127.

kcross -- controller 4, crossfade of modulator. Value range of kv2 is 0-127.

klfo -- controller 11, speed of low-frequency oscillator. Value range of
kv3 is 0-127.

klfodepth -- controller 1, depth of low-frequency oscillator. Value
range of kv4 is 0-127.

kadsr -- controller 128, ADSR 2 and 4 target. Value range of kv5 is 0-127.

  Note

The code for this opcode is taken directly from the HevyMetl class in
the Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More
on the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKMandolin                                                     *STKMandolin*

  Description

STKMandolin produces mamdolin-like sounds, using "commuted synthesis"
techniques to model a mandolin instrument.

  Syntax

asignal STKMandolin ifrequency, iamplitude, [kbody, kv1[, kpos, kv2[, ksus, kv3[, kdetune, kv4[, kmic, kv5]]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

kbody -- controller 2, size of body. Value range of kv1 is 0-127.

kpos -- controller 4, pluck position. Value range of kv2 is 0-127.

ksus -- controller 11, string sustain. Value range of kv3 is 0-127.

kdetune -- controller 1, string detuning. Value range of kv4 is 0-127.

kmic -- controller 128, position of microphone. Value range of kv5 is 0-127.

  Note

The code for this opcode is taken directly from the Mandolin class in
the Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More
on the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKModalBar                                                     *STKModalBar*

  Description

This opcode is a resonant bar instrument.It has a number of different
struck bar instruments.

  Syntax

asignal STKModalBar ifrequency, iamplitude, [khard, kv1[, kpos, kv2[, klfo, kv3[, klfodepth, kv4[, kmix, kv5[, kvol, kv6[, kinstr, kv7]]]]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

khard -- controller 2, hardness of the stick. Value range of kv1 is 0-127.

kpos -- controller 4, stick position. Value range of kv2 is 0-127.

klfo -- controller 11, speed of low-frequency oscillator. Value range of
kv3 is 0-127.

klfodepth -- controller 1, depth of low-frequency oscillator. Value
range of kv4 is 0-127.

kmix -- controller 8, direct stick mix. Value range of kv5 is 0-127.

kvol -- controller 128, volume. Value range of kv6 is 0-127.

kinstr -- controller 16, instrument presets (0 = marimba, 1 =
vibraphone, 2 = agogo, 3 = wood1, 4 = reso, 5 = wood2, 6 = beats, 7 =
two fixed, 8 = clump). Value range of kv7 is 0-16.

  Note

The code for this opcode is taken directly from the ModalBar class in
the Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More
on the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKMoog                                                             *STKMoog*

  Description

STKMoog produces moog-like swept filter sounds, using one attack wave,
one looped wave, and an ADSR envelope and adds two sweepable formant
filters.

  Syntax

asignal STKMoog ifrequency, iamplitude, [kq, kv1[, krate, kv2[, klfo, kv3[, klfodepth, kv4[, kvol, kv5]]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

kq -- controller 2, Q filter. Value range of kv1 is 0-127.

krate -- controller 4, rate of filter sweep. Value range of kv2 is 0-127.

klfo -- controller 11, speed of low-frequency oscillator. Value range of
kv3 is 0-127.

klfodepth -- controller 1, depth of low-frequency oscillator. Value
range of kv4 is 0-127.

kvol -- controller 128, volume. Value range of kv5 is 0-127.

  Note

The code for this opcode is taken directly from the Moog class in the
Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More on
the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKPercFlut                                                     *STKPercFlut*

  Description

STKPercFlut is a percussive flute FM synthesis instrument. The
instrument uses an algorithm like the algorithm 4 of the TX81Z.

  Syntax

asignal STKPercFlut ifrequency, iamplitude, [kmod, kv1[, kcross, kv2[, klfo, kv3[, klfodepth, kv4[, kadsr, kv5]]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

kmod -- controller 2, total modulator index. Value range of kv1 is 0-127.

kcross -- controller 4, crossfade of modulator. Value range of kv2 is 0-127.

klfo -- controller 11, speed of low-frequency oscillator. Value range of
kv3 is 0-127.

klfodepth -- controller 1, depth of low-frequency oscillator. Value
range of kv4 is 0-127.

kadsr -- controller 128, ADSR 2 and 4 target. Value range of kv5 is 0-127.

  Note

The code for this opcode is taken directly from the PercFlut class in
the Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More
on the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKPlucked                                                       *STKPlucked*

  Description

STKPlucked uses a plucked string physical model based on the
Karplus-Strong algorithm.

  Syntax

asignal STKPlucked ifrequency, iamplitude

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Note

The code for this opcode is taken directly from the Plucked class in the
Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More on
the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html


===========================================================================
STKResonate                                                     *STKResonate*

  Description

STKResonate is a noise driven formant filter. This instrument contains a
noise source, which excites a biquad resonance filter, with volume
controlled by an ADSR.

  Syntax

asignal STKResonate ifrequency, iamplitude, [kfreq, kv1[, kpole, kv2[, knotch, kv3[, kzero, kv4[, kenv, kv5]]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

kfreq -- controller 2, frequency of resonance. Value range of kv1 is 0-127.

kpole -- controller 4, pole radii. Value range of kv2 is 0-127.

knotch -- controller 11, notch frequency. Value range of kv3 is 0-127.

kzero -- controller 1, zero radii. Value range of kv4 is 0-127.

kenv -- controller 128, gain of envelope. Value range of kv5 is 0-127.

  Note

The code for this opcode is taken directly from the Resonate class in
the Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More
on the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKRhodey                                                         *STKRhodey*

  Description

STK Fender Rhodes-like electric piano FM synthesis instrument.

This opcode implements an instrument based on two simple FM Pairs summed
together, also referred to as algorithm 5 of the Yamaha TX81Z. It
simulates the sound of a Rhodes electric piano, and some related sounds.

  Syntax

asignal STKRhodey ifrequency, iamplitude, [kmod, kv1[, kcross, kv2[, klfo, kv3[, klfodepth, kv4[, kadsr, kv5]]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

kmod -- controller 2, modulator index 1. Value range of kv1 is 0-127.

kcross -- controller 4, crossfade of outputs. Value range of kv2 is 0-127.

klfo -- controller 11, speed of low-frequency oscillator. Value range of
kv3 is 0-127.

klfodepth -- controller1, depth of low-frequency oscillator. Value range
of kv4 is 0-127.

kadsr -- controller 128, ADSR 2 and 4 target. Value range of kv5 is 0-127.

  Note

The code for this opcode is taken directly from the Rhodey class in the
Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More on
the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKSaxofony                                                     *STKSaxofony*

  Description

STKSaxofony is a faux conical bore reed instrument. This opcode uses a
"hybrid" digital waveguide instrument that can generate a variety of
wind-like sounds. It has also been referred to as the "blowed string"
model. The waveguide section is essentially that of a string, with one
rigid and one lossy termination. The non-linear function is a reed
table. The string can be "blown" at any point between the terminations,
though just as with strings, it is impossible to excite the system at
either end. If the excitation is placed at the string mid-point, the
sound is that of a clarinet. At points closer to the "bridge", the sound
is closer to that of a saxophone.

  Syntax

asignal STKSaxofony ifrequency, iamplitude, [kstiff, kv1[, kapert, kv2[, kblow, kv3[, knoise, kv4[, klfo, kv5[, klfodepth, kv6[, kbreath, kv7]]]]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

kstiff -- controller 2, stiffness of reed. Value range of kv1 is 0-127.

kapert -- controller 26, reed aperture. Value range of kv2 is 0-127.

kblow -- controller 11, blow position. Value range of kv3 is 0-127.

knoise -- controller 4, noise gain. Value range of kv4 is 0-127.

klfo -- controller 29, speed of low-frequency oscillator. Value range of
kv5 is 0-127.

klfodepth -- controller 1, depth of low-frequency oscillator. Value
range of kv6 is 0-127.

kbreath -- controller 128, breath pressure. Value range of kv7 is 0-127.

  Note

The code for this opcode is taken directly from the Saxofony class in
the Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More
on the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKShakers                                                       *STKShakers*

  Description

STKShakers are a set of PhISEM and PhOLIES instruments: PhISEM
(Physically Informed Stochastic Event Modeling) is an algorithmic
approach for simulating collisions of multiple independent sound
producing objects. It can simulate a Maraca, Sekere, Cabasa, Bamboo Wind
Chimes, Water Drops, Tambourine, Sleighbells, and a Guiro. On
http://soundlab.cs.princeton.edu/research/controllers/shakers/ PhOLIES
(Physically-Oriented Library of Imitated Environmental Sounds) there is
a similar approach for the synthesis of environmental sounds. It
simulates of breaking sticks, crunchy snow (or not), a wrench,
sandpaper, and more..

  Syntax

asignal STKShakers ifrequency, iamplitude, [kenerg, kv1[, kdecay, kv2[, kshake, kv3[, knum, kv4[, kres, kv5[, kinstr, kv6]]]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

kenerg -- controller 2, shake energy. Value range of kv1 is 0-127.

kdecay -- controller 4, system decay. Value range of kv2 is 0-127.

kshake -- controller 128, shake energy. Value range of kv3 is 0-127.

knum -- controller 11, number of objects. Value range of kv4 is 0-127.

kres -- controller 1, resonance frequency. Value range of kv5 is 0-127.

kinstr -- controller 1071, instrument selection (Maraca = 0, Cabasa = 1,
Sekere = 2, Guiro = 3, Water Drops = 4, Bamboo Chimes = 5, Tambourine =
6, Sleigh Bells = 7, Sticks = 8, Crunch = 9, Wrench = 10, Sand Paper =
11, Coke Can = 12, Next Mug = 13, Penny + Mug = 14, Nickle + Mug = 15,
Dime + Mug = 16, Quarter + Mug = 17, Franc + Mug = 18, Peso + Mug = 19,
Big Rocks = 20, Little Rocks = 21, Tuned Bamboo Chimes = 22). Value
range of kv6 is 0-22.

  Note

The code for this opcode is taken directly from the Shakers class in the
Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More on
the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKSimple                                                         *STKSimple*

  Description

STKSimple is a wavetable/noise instrument. It combines a looped wave, a
noise source, a biquad resonance filter, a one-pole filter, and an ADSR
envelope to create some interesting sounds.

  Syntax

asignal STKSimple ifrequency, iamplitude, [kpos, kv1[, kcross, kv2[, kenv, kv3[, kgain, kv4]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

kpos -- controller 2, position of filter pole. Value range of kv1 is 0-127.

kcross -- controller 4, noise/pitched cross-fade. Value range of kv2 is
0-127.

kenv -- controller 11, rate of envelope. Value range of kv3 is 0-127.

kgain -- controller 128, gain. Value range of kv4 is 0-127.

  Note

The code for this opcode is taken directly from the Simple class in the
Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More on
the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKSitar                                                           *STKSitar*

  Description

STKSitar uses a plucked string physical model based on the
Karplus-Strong algorithm.

  Syntax

asignal STKSitar ifrequency, iamplitude

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Note

The code for this opcode is taken directly from the Sitar class in the
Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More on
the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html


===========================================================================
STKStifKarp                                                     *STKStifKarp*

  Description

STKStifKarp is a plucked stiff string instrument. It a simple plucked
string algorithm (Karplus Strong) with enhancements, including string
stiffness and pluck position controls. The stiffness is modeled with
allpass filters.

  Syntax

asignal STKStifKarp ifrequency, iamplitude, [kpos, kv1[, ksus, kv2[, kstretch, kv3]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

kpos -- controller 4, pickup position. Value range of kv1 is 0-127.

ksus -- controller11, string sustain. Value range of kv2 is 0-127.

kstretch -- controller 1, string stretch. Value range of kv3 is 0-127.

  Note

The code for this opcode is taken directly from the StifKarp class in
the Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More
on the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKTubeBell                                                     *STKTubeBell*

  Description

STKTubeBell is a tubular bell (orchestral chime) FM synthesis
instrument. It uses two simple FM Pairs summed together, also referred
to as algorithm 5 of the TX81Z.

  Syntax

asignal STKTubeBell ifrequency, iamplitude, [kmod, kv1[, kcross, kv2[, klfo, kv3[, klfodepth, kv4[, kadsr, kv5]]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

kmod -- controller 2, modulator index 1. Value range of kv1 is 0-127.

kcross -- controller 4, crossfade of outputs. Value range of kv2 is 0-127.

klfo -- controller 11, speed of low-frequency oscillator. Value range of
kv3 is 0-127.

klfodepth -- controller 1, depth of low-frequency oscillator. Value
range of kv4 is 0-127.

kadsr -- controller 128, ADSR 2 and 4 target. Value range of kv5 is 0-127.

  Note

The code for this opcode is taken directly from the TubeBell class in
the Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More
on the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKVoicForm                                                     *STKVoicForm*

  Description

STKVoicForm is a four formant synthesis instrument. This instrument
contains an excitation singing wavetable (looping wave with random and
periodic vibrato, smoothing on frequency, etc.), excitation noise, and
four sweepable complex resonances. Measured formant data is included,
and enough data is there to support either parallel or cascade
synthesis. In the floating point case cascade synthesis is the most
natural so that's what you'll find here.

  Syntax

asignal STKVoicForm ifrequency, iamplitude, [kmix, kv1[, ksel, kv2[, klfo, kv3[, klfodepth, kv4[, kloud, kv5]]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

kmix -- controller 2, voiced/unvoiced mix. Value range of kv1 is 0-127.

ksel -- controller 4, vowel/phoneme selection. Value range of kv2 is 0-127.

klfo -- controller 11, speed of low-frequency oscillator. Value range of
kv3 is 0-127.

klfodepth -- controller 1, depth of low-frequency oscillator. Value
range of kv4 is 0-127.

kloud -- controller 128, loudness (spectral tilt). Value range of kv5 is
0-127.

  Note

The code for this opcode is taken directly from the VoicForm class in
the Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More
on the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKWhistle                                                       *STKWhistle*

  Description

STKWhistle produces (police) whistle sounds. It uses a hybrid
physical/spectral model of a police whistle (a la Cook).

  Syntax

asignal STKWhistle ifrequency, iamplitude, [kmod, kv1[, knoise, kv2[, kfipfreq, kv3[, kfipgain, kv4[, kvol, kv5]]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

kmod -- controller 2, blowing frequency modulation. Value range of kv1
is 0-127.

knoise -- controller 4, noise gain. Value range of kv2 is 0-127.

kfipfreq -- controller 11, fipple modulation frequency. Value range of
kv3 is 0-127.

kfipgain -- controller 1, fipple modulation gain. Value range of kv4 is
0-127.

kvol -- controller 128, volume. Value range of kv5 is 0-127.

  Note

The code for this opcode is taken directly from the Whistle class in the
Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More on
the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
STKWurley                                                         *STKWurley*

  Description

STKWurley simulates a Wurlitzer electric piano FM synthesis instrument.
It uses two simple FM Pairs summed together, also referred to as
algorithm 5 of the TX81Z.

  Syntax

asignal STKWurley ifrequency, iamplitude, [kmod, kv1[, kcross, kv2[, klfo, kv3[, klfodepth, kv4[, kadsr, kv5]]]]]

  Initialization

ifrequency -- Frequency of note played, in Hertz.

iamplitude -- Amplitude of note played (range 0-1).

  Performance

kmod -- controller 2, modulator index 1. Value range of kv1 is 0-127.

kcross -- controller 4, crossfade of outputs. Value range of kv2 is 0-127.

klfo -- controller 11, speed of low-frequency oscillator. Value range of
kv3 is 0-127.

klfodepth -- controller1, depth of low-frequency oscillator. Value range
of kv4 is 0-127.

kadsr -- controller 128, ADSR 2 and 4 target. Value range of kv5 is 0-127.

  Note

The code for this opcode is taken directly from the Wurley class in the
Synthesis Toolkit in C++ by Perry R. Cook and Gary P. Scavone. More on
the STK classes can be found here:
https://ccrma.stanford.edu/software/stk/classes.html

kc1, kv1, kc2, kv2, kc3, kv3, kc4, kv4, kc5, kv5, kc6, kv6, kc7, kv7,
kc8, kv8 -- Up to 8 optional k-rate controller pairs for the STK
opcodes. Each controller pair consists of a controller number (kc)
followed by a controller value (kv). Both the controller numbers and the
controller values are krate variables. However, during a performance,
normally the controller numbers stay fixed while the corresponding
controller values may change at any time. The order of the controller
pair is arbitrary, as long as they are after iamplitude. Also, it is not
needed that all controller pairs are used.


===========================================================================
strchar                                                             *strchar*

  Description

Return the ASCII code of the character in Sstr at ipos (defaults to zero
which means the first character), or zero if ipos is out of range.
strchar runs at init time only.

  Syntax

ichr strchar Sstr[, ipos]


===========================================================================
strchark                                                           *strchark*

  Description

Return the ASCII code of the character in Sstr at kpos (defaults to zero
which means the first character), or zero if kpos is out of range.
strchark runs both at init and performance time.

  Syntax

kchr strchark Sstr[, kpos]


===========================================================================
strcpy                                                               *strcpy*

  Description

Assign to a string variable by copying the source which may be a
constant or another string variable. strcpy and = copy the string at
i-time only.

  Syntax

Sdst strcpy Ssrc

Sdst = Ssrc


===========================================================================
strcpyk                                                             *strcpyk*

  Description

Assign to a string variable by copying the source which may be a
constant or another string variable. strcpyk does the assignment both at
initialization and performance time.

  Syntax

Sdst strcpyk Ssrc


===========================================================================
strcat                                                               *strcat*

  Description

Concatenate two strings and store the result in a variable. strcat runs
at i-time only. It is allowed for any of the input arguments to be the
same as the output variable.

  Syntax

Sdst strcat Ssrc1, Ssrc2


===========================================================================
strcatk                                                             *strcatk*

  Description

Concatenate two strings and store the result in a variable. strcatk does
the concatenation both at initialization and performance time. It is
allowed for any of the input arguments to be the same as the output
variable.

  Syntax

Sdst strcatk Ssrc1, Ssrc2


===========================================================================
strcmp                                                               *strcmp*

  Description

Compare strings and set the result to -1, 0, or 1 if the first string is
less than, equal to, or greater than the second, respectively. strcmp
compares at i-time only.

  Syntax

ires strcmp S1, S2


===========================================================================
strcmpk                                                             *strcmpk*

  Description

Compare strings and set the result to -1, 0, or 1 if the first string is
less than, equal to, or greater than the second, respectively. strcmpk
does the comparison both at initialization and performance time.

  Syntax

kres strcmpk S1, S2


===========================================================================
streson                                                             *streson*

  Description

An audio signal is modified by a string resonator with variable
fundamental frequency.

  Syntax

ares streson asig, kfr, ifdbgain

  Initialization

ifdbgain -- feedback gain, between 0 and 1, of the internal delay line.
A value close to 1 creates a slower decay and a more pronounced
resonance. Small values may leave the input signal unaffected. Depending
on the filter frequency, typical values are > .9.

  Performance

asig -- the input audio signal.

kfr -- the fundamental frequency of the string.

streson passes the input asig through a network composed of comb,
low-pass and all-pass filters, similar to the one used in some versions
of the Karplus-Strong algorithm, creating a string resonator effect. The
fundamental frequency of the “string” is controlled by the k-rate
variable kfr.This opcode can be used to simulate sympathetic resonances
to an input signal.

See Modal Frequency Ratios for frequency ratios of real intruments which
can be used to determine the values of kfrq.

streson is an adaptation of the StringFlt object of the SndObj Sound
Object Library developed by the author.


===========================================================================
strfromurl                                                       *strfromurl*

  Description

strfromurl sets a string variable at initialization time to the value
found from reading an URL.

  Syntax

Sdst strfromurl StringURL

  Initialization

StringURL -- string naming an URL.

Sdst -- destination string variable


===========================================================================
strget                                                               *strget*

  Description

strget sets a string variable at initialization time to the value stored
in strset table at the specified index, or a string p-field from the
score. If there is no string defined for the index, the variable is set
to an empty string.

  Syntax

Sdst strget indx

  Initialization

indx -- strset index, or score p-field

Sdst -- destination string variable


===========================================================================
strindex                                                           *strindex*

  Description

Return the position of the first occurence of S2 in S1, or -1 if not
found. If S2 is empty, 0 is returned. strindex runs at init time only.

  Syntax

ipos strindex S1, S2


===========================================================================
strindexk                                                         *strindexk*

  Description

Return the position of the first occurence of S2 in S1, or -1 if not
found. If S2 is empty, 0 is returned. strindexk runs both at init and
performance time.

  Syntax

kpos strindexk S1, S2


===========================================================================
strlen                                                               *strlen*

  Description

Return the length of a string, or zero if it is empty. strlen runs at
init time only.

  Syntax

ilen strlen Sstr


===========================================================================
strlenk                                                             *strlenk*

  Description

Return the length of a string, or zero if it is empty. strlenk runs both
at init and performance time.

  Syntax

klen strlenk Sstr


===========================================================================
strlower                                                           *strlower*

  Description

Convert Ssrc to lower case, and write the result to Sdst. strlower runs
at init time only.

  Syntax

Sdst strlower Ssrc


===========================================================================
strlowerk                                                         *strlowerk*

  Description

Convert Ssrc to lower case, and write the result to Sdst. strlowerk runs
both at init and performance time.

  Syntax

Sdst strlowerk Ssrc


===========================================================================
strrindex                                                         *strrindex*

  Description

Return the position of the last occurence of S2 in S1, or -1 if not
found. If S2 is empty, the length of S1 is returned. strrindex runs at
init time only.

  Syntax

ipos strrindex S1, S2


===========================================================================
strrindexk                                                       *strrindexk*

  Description

Return the position of the last occurence of S2 in S1, or -1 if not
found. If S2 is empty, the length of S1 is returned. strrindexk runs
both at init and performance time.

  Syntax

kpos strrindexk S1, S2


===========================================================================
strset                                                               *strset*

  Description

Allows a string to be linked with a numeric value.

  Syntax

strset iarg, istring

  Initialization

iarg -- the numeric value.

istring -- the alphanumeric string (in double-quotes).

strset (optional) allows a string, such as a filename, to be linked with
a numeric value. Its use is optional.


===========================================================================
strsub                                                               *strsub*

  Description

Return a substring of the source string. strsub runs at init time only.

  Syntax

Sdst strsub Ssrc[, istart[, iend]]

  Initialization

istart (optional, defaults to 0) -- start position in Ssrc, counting
from 0. A negative value means the end of the string.

iend (optional, defaults to -1) -- end position in Ssrc, counting from
0. A negative value means the end of the string. If iend is less than
istart, the output is reversed.


===========================================================================
strsubk                                                             *strsubk*

  Description

Return a substring of the source string. strsubk runs both at init and
performance time.

  Syntax

Sdst strsubk Ssrc, kstart, kend

  Performance

kstart -- start position in Ssrc, counting from 0. A negative value
means the end of the string.

kend -- end position in Ssrc, counting from 0. A negative value means
the end of the string. If kend is less than kstart, the output is reversed.


===========================================================================
strtod                                                               *strtod*

  Description

Convert a string to a floating point value. It is also possible to pass
an strset index or a string p-field from the score instead of a string
argument. If the string cannot be parsed as a floating point or integer
number, an init or perf error occurs and the instrument is deactivated.

  Syntax

ir strtod Sstr

ir strtod indx

  Initialization

Sstr -- String to convert.

indx -- index of string set by strset

  Performance

ir -- Value of string as float.


===========================================================================
strtodk                                                             *strtodk*

  Description

Convert a string to a floating point value at i- or k-rate. It is also
possible to pass an strset index or a string p-field from the score
instead of a string argument. If the string cannot be parsed as a
floating point or integer number, an init or perf error occurs and the
instrument is deactivated.

  Note

If a k-rate index variable is used, it should be valid at i-time as well.

  Syntax

kr strtodk Sstr

kr strtodk kndx

  Performance

kr -- Value of string as float.

Sstr -- String to convert.

indx -- index of string set by strset


===========================================================================
strtol                                                               *strtol*

  Description

Convert a string to a signed integer value. It is also possible to pass
an strset index or a string p-field from the score instead of a string
argument. If the string cannot be parsed as an integer number, an init
error occurs and the instrument is deactivated.

  Syntax

ir strtol Sstr

ir strtol indx

  Initialization

Sstr -- String to convert.

indx -- index of string set by strset

strtol can parse numbers in decimal, octal (prefixed by 0), and
hexadecimal (with a prefix of 0x) format.

  Performance

ir -- Value of string as signed integer.


===========================================================================
strtolk                                                             *strtolk*

  Description

Convert a string to a signed integer value at i- or k-rate. It is also
possible to pass an strset index or a string p-field from the score
instead of a string argument. If the string cannot be parsed as an
integer number, an init or perf error occurs and the instrument is
deactivated.

  Note

If a k-rate index variable is used, it should be valid at i-time as well.

  Syntax

kr strtolk Sstr

kr strtolk kndx

strtolk can parse numbers in decimal, octal (prefixed by 0), and
hexadecimal (with a prefix of 0x) format.

  Performance

kr -- Value of string as signed integer.

Sstr -- String to convert.

indx -- index of string set by strset


===========================================================================
strupper                                                           *strupper*

  Description

Convert Ssrc to upper case, and write the result to Sdst. strupper runs
at init time only.

  Syntax

Sdst strupper Ssrc


===========================================================================
strupperk                                                         *strupperk*

  Description

Convert Ssrc to upper case, and write the result to Sdst. strupperk runs
both at init and performance time.

  Syntax

Sdst strupperk Ssrc


===========================================================================
subinstr                                                           *subinstr*

  Description

Creates an instance of another instrument and is used as if it were an
opcode.

  Syntax

a1, [...] [, a8] subinstr instrnum [, p4] [, p5] [...]

a1, [...] [, a8] subinstr "insname" [, p4] [, p5] [...]

  Initialization

instrnum -- Number of the instrument to be called.

“insname” -- A string (in double-quotes) representing a named instrument.

  Performance

a1, ..., a8 -- The audio output from the called instrument. This is
generated using the signal output opcodes.

p4, p5, ... -- Additional input values the are mapped to the called
instrument p-fields, starting with p4.

The called instrument's p2 and p3 values will be identical to the host
instrument's values. While the host instrument can control its own
duration, any such attempts inside the called instrument will most
likely have no effect.


===========================================================================
subinstrinit                                                   *subinstrinit*

  Description

Same as subinstr, but init-time only and has no output arguments.

  Syntax

subinstrinit instrnum [, p4] [, p5] [...]

subinstrinit "insname" [, p4] [, p5] [...]

  Initialization

instrnum -- Number of the instrument to be called.

“insname” -- A string (in double-quotes) representing a named instrument.

p4, p5, ... -- Additional input values the are mapped to the called
instrument p-fields, starting with p4.

The called instrument's p2 and p3 values will be identical to the host
instrument's values. While the host instrument can control its own
duration, any such attempts inside the called instrument will most
likely have no effect.


===========================================================================
sum                                                                     *sum*

  Description

Sums any number of a-rate signals.

  Syntax

ares sum asig1 [, asig2] [, asig3] [...]

  Performance

asig1, asig2, ... -- a-rate signals to be summed (mixed or added).


===========================================================================
sumarray                                                           *sumarray*

  Description

The sumarray opcode returns the sum of all elements in a k-rate array
array.

  Syntax

ksum sumarray karray

  Performance

ksum -- variable for result.

karray -- array for reading.


===========================================================================
svfilter                                                           *svfilter*

  Description

Implementation of a resonant second order filter, with simultaneous
lowpass, highpass and bandpass outputs.

  Syntax

alow, ahigh, aband svfilter  asig, kcf, kq [, iscl] [, iskip]

  Initialization

iscl -- coded scaling factor, similar to that in reson. A non-zero value
signifies a peak response factor of 1, i.e. all frequencies other than
kcf are attenuated in accordance with the (normalized) response curve. A
zero value signifies no scaling of the signal, leaving that to some
later adjustment (see balance). The default value is 0.

iskip (optional, default=0) -- initial disposition of internal data
space. Since filtering incorporates a feedback loop of previous output,
the initial status of the storage space used is significant. A zero
value will clear the space; a non-zero value will allow previous
information to remain. The default value is 0.

  Performance

svfilter is a second order state-variable filter, with k-rate controls
for cutoff frequency and Q. As Q is increased, a resonant peak forms
around the cutoff frequency. svfilter has simultaneous lowpass,
highpass, and bandpass filter outputs; by mixing the outputs together, a
variety of frequency responses can be generated. The state-variable
filter, or "multimode" filter was a common feature in early analog
synthesizers, due to the wide variety of sounds available from the
interaction between cutoff, resonance, and output mix ratios. svfilter
is well suited to the emulation of "analog" sounds, as well as other
applications where resonant filters are called for.

kcf -- Cutoff or resonant frequency of the filter, measured in Hz.

kq -- Q of the filter, which is defined (for bandpass filters) as
bandwidth/cutoff. kq should be in a range between 1 and 500. As kq is
increased, the resonance of the filter increases, which corresponds to
an increase in the magnitude and "sharpness" of the resonant peak. When
using svfilter without any scaling of the signal (where iscl is either
absent or 0), the volume of the resonant peak increases as Q increases.
For high values of Q, it is recommended that iscl be set to a non-zero
value, or that an external scaling function such as balance is used.

svfilter is based upon an algorithm in Hal Chamberlin's Musical
Applications of Microprocessors (Hayden Books, 1985).


===========================================================================
syncgrain                                                         *syncgrain*

  Description

syncgrain implements synchronous granular synthesis. The source sound
for the grains is obtained by reading a function table containing the
samples of the source waveform. For sampled-sound sources, GEN01 is
used. syncgrain will accept deferred allocation tables.

The grain generator has full control of frequency (grains/sec), overall
amplitude, grain pitch (a sampling increment) and grain size (in secs),
both as fixed or time-varying (signal) parameters. An extra parameter is
the grain pointer speed (or rate), which controls which position the
generator will start reading samples in the table for each successive
grain. It is measured in fractions of grain size, so a value of 1 (the
default) will make each successive grain read from where the previous
grain should finish. A value of 0.5 will make the next grain start at
the midway position from the previous grain start and finish, etc.. A
value of 0 will make the generator read always from a fixed position of
the table (wherever the pointer was last at). A negative value will
decrement pointer positions. This control gives extra flexibility for
creating timescale modifications in the resynthesis.

syncgrain will generate any number of parallel grain streams (which will
depend on grain density/frequency), up to the iolaps value (default
100). The number of streams (overlapped grains) is determined by
grainsize*grain_freq. More grain overlaps will demand more calculations
and the synthesis might not run in realtime (depending on processor power).

syncgrain can simulate FOF-like formant synthesis, provided that a
suitable shape is used as grain envelope and a sinewave as the grain
wave. For this use, grain sizes of around 0.04 secs can be used. The
formant centre frequency is determined by the grain pitch. Since this is
a sampling increment, in order to use a frequency in Hz, that value has
to be scaled by tablesize/sr. Grain frequency will determine the
fundamental.

syncgrain uses floating-point indexing, so its precision is not affected
by large-size tables. This opcode is based on the SndObj library
SyncGrain class.

  Syntax

asig syncgrain kamp, kfreq, kpitch, kgrsize, kprate, ifun1, \
      ifun2, iolaps

  Initialization

ifun1 -- source signal function table. Deferred-allocation tables (see
GEN01) are accepted, but the opcode expects a mono source.

ifun2 -- grain envelope function table.

iolaps -- maximum number of overlaps, max(kfreq)*max(kgrsize).
Estimating a large value should not affect performance, but exceeding
this value will probably have disastrous consequences.

  Performance

kamp -- amplitude scaling

kfreq -- frequency of grain generation, or density, in grains/sec.

kpitch -- grain pitch scaling (1=normal pitch, < 1 lower, > 1 higher;
negative, backwards)

kgrsize -- grain size in secs.

kprate -- readout pointer rate, in grains. The value of 1 will advance
the reading pointer 1 grain ahead in the source table. Larger values
will time-compress and smaller values will time-expand the source
signal. Negative values will cause the pointer to run backwards and zero
will freeze it.


===========================================================================
syncloop                                                           *syncloop*

  Description

syncloop is a variation on syncgrain, which implements synchronous
granular synthesis. syncloop adds loop start and end points and an
optional start position. Loop start and end control grain start
positions, so the actual grains can go beyond the loop points (if the
loop points are not at the extremes of the table), enabling seamless
crossfading. For more information on the granular synthesis process,
check the syncgrain manual page.

  Syntax

asig syncloop kamp, kfreq, kpitch, kgrsize, kprate, klstart, \
      klend, ifun1, ifun2, iolaps[,istart, iskip]

  Initialization

ifun1 -- source signal function table. Deferred-allocation tables (see
GEN01) are accepted, but the opcode expects a mono source.

ifun2 -- grain envelope function table.

iolaps -- maximum number of overlaps, max(kfreq)*max(kgrsize).
Estimating a large value should not affect performance, but execeeding
this value will probably have disastrous consequences.

istart -- starting point of synthesis in secs (defaults to 0).

iskip -- if 1, the opcode initialisation is skipped, for tied notes,
performance continues from the position in the loop where the previous
note stopped. The default, 0, does not skip initialisation

  Performance

kamp -- amplitude scaling

kfreq -- frequency of grain generation, or density, in grains/sec.

kpitch -- grain pitch scaling (1=normal pitch, < 1 lower, > 1 higher;
negative, backwards)

kgrsize -- grain size in secs.

kprate -- readout pointer rate, in grains. The value of 1 will advance
the reading pointer 1 grain ahead in the source table. Larger values
will time-compress and smaller values will time-expand the source
signal. Negative values will cause the pointer to run backwards and zero
will freeze it.

klstart -- loop start in secs.

klend -- loop end in secs.


===========================================================================
syncphasor                                                       *syncphasor*

  Description

Produces a moving phase value between zero and one and an extra impulse
output ("sync out") whenever its phase value crosses or is reset to
zero. The phase can be reset at any time by an impulse on the "sync in"
parameter.

  Syntax

aphase, asyncout syncphasor xcps, asyncin, [, iphs]

  Initialization

iphs (optional) -- initial phase, expressed as a fraction of a cycle (0
to 1). A negative value will cause phase initialization to be skipped.
The default value is zero.

  Performance

aphase -- the output phase value; always between 0 and 1.

asyncout -- the sync output has a value of 1.0 for one sample whenever
the phase value crosses zero or whenever the sync input is non-zero. It
is zero at all other times.

asyncin -- the sync input causes the phase to reset to zero whenever
asyncin is non-zero.

xcps -- frequency of the phasor in cycles-per-second. If xcps is
negative, the phase value will decrease from 1 to 0 instead of increasing.

An internal phase is successively accumulated in accordance with the
xcps frequency to produce a moving phase value, normalized to lie in the
range 0 <= phs < 1. When used as the index to a table unit, this phase
(multiplied by the desired function table length) will cause it to
behave like an oscillator.

The phase of syncphasor though can be synced to another phasor (or other
signal) using the asyncin parameter. Any time that asyncin is a non-zero
value, the value of aphase will be reset to zero. syncphasor also
outputs its own "sync" signal that consists of a one-sample impulse
whenever its phase crosses zero or is reset. This makes it easy to chain
together multiple syncphasor opcodes to create an oscillator "hard sync"
effect.


===========================================================================
system                                                               *system*

  Description

system and system_i call any external command understood by the
operating system, similarly to the C function system(). system_i runs at
i-time only, while system runs both at initialization and performance time.

  Syntax

ires system_i itrig, Scmd, [inowait]

kres system ktrig, Scmd, [knowait]

  Initialization

Scmd -- command string

itrig -- if greater than zero the opcode executes the command; otherwise
it is an null operation.

  Performance

ktrig -- if greater than zero and different from the value on the
previous control cycle the opcode executes the command. Initially this
previous value is taken as zero.

inowait,knowait -- if given an non zero the command is run in the
background and the command does not wait for the result. (default = 0)

ires, kres -- the return code of the command in wait mode and if the
command is run.In other cases returns zero.

More than one system command (a script) can be executed with a single
system opcode by using double braces strings {{ }}.

  Note
This opcode is very system dependant, so should be used with extreme
care (or not used) if platform neutrality is desired.

tb0, tb1, tb2, tb3, tb4, tb5, tb6, tb7, tb8, tb9, tb10, tb11, tb12,
tb13, tb14, tb15, tb0_init, tb1_init, tb2_init, tb3_init, tb4_init,
tb5_init, tb6_init, tb7_init, tb8_init, tb9_init, tb10_init, tb11_init,
  Description

Allow to read tables in function fashion, to be used inside expressions.
At present time Csound only supports functions with a single input
argument. However, to access table elements, user must provide two
numbers, i.e. the number of table and the index of element. So, in order
to allow to access a table element with a function, a previous
preparation step should be done.

  Syntax

tb0_init ifn

tb1_init ifn

tb2_init ifn

tb3_init ifn

tb4_init ifn

tb5_init ifn

tb6_init ifn

tb7_init ifn

tb8_init ifn

tb9_init ifn

tb10_init ifn

tb11_init ifn

tb12_init ifn

tb13_init ifn

tb14_init ifn

tb15_init ifn

iout = tb0(iIndex)

kout = tb0(kIndex)

iout = tb1(iIndex)

kout = tb1(kIndex)

iout = tb2(iIndex)

kout = tb2(kIndex)

iout = tb3(iIndex)

kout = tb3(kIndex)

iout = tb4(iIndex)

kout = tb4(kIndex)

iout = tb5(iIndex)

kout = tb5(kIndex)

iout = tb6(iIndex)

kout = tb6(kIndex)

iout = tb7(iIndex)

kout = tb7(kIndex)

iout = tb8(iIndex)

kout = tb8(kIndex)

iout = tb9(iIndex)

kout = tb9(kIndex)

iout = tb10(iIndex)

kout = tb10(kIndex)

iout = tb11(iIndex)

kout = tb11(kIndex)

iout = tb12(iIndex)

kout = tb12(kIndex)

iout = tb13(iIndex)

kout = tb13(kIndex)

iout = tb14(iIndex)

kout = tb14(kIndex)

iout = tb15(iIndex)

kout = tb15(kIndex)

  Performance

There are 16 different opcodes whose name is associated with a number
from 0 to 15. User can associate a specific table with each opcode (so
the maximum number of tables that can be accessed in function fashion is
16). Prior to access a table, user must associate the table with one of
the 16 opcodes by means of an opcode chosen among tb0_init, ...,
tb15_init. For example,

      tb0_init  1

associates table 1 with tb0( ) function, so that, each element of table
1 can be accessed (in function fashion) with:

      kvar = tb0(k_some_index_of_table1) * k_some_other_var

      ivar = tb0(i_some_index_of_table1) + i_some_other_var

etc...

By using these opcodes, user can drastically reduce the number of lines
of an orchestra, improving its readability.


===========================================================================
tab                                                                     *tab*

  Description

Fast table opcodes. Faster than table and tablew because don't allow
wrap-around and limit and don't check index validity. Have been
implemented in order to provide fast access to arrays. Support non-power
of two tables (can be generated by any GEN function by giving a negative
length value).

  Syntax

ir tab_i indx, ifn[, ixmode]

kr tab kndx, ifn[, ixmode]

ar tab xndx, ifn[, ixmode]

tabw_i isig, indx, ifn [,ixmode]

tabw ksig, kndx, ifn [,ixmode]

tabw asig, andx, ifn [,ixmode]

  Initialization

ifn -- table number

ixmode -- defaults to zero. If zero xndx and ixoff ranges match the
length of the table; if non zero xndx and ixoff have a 0 to 1 range.

isig -- input value to write.

indx -- table index

  Performance

asig, ksig -- input signal to write.

andx, kndx -- table index.

tab and tabw opcodes are similar to table and tablew, but are faster and
support tables having non-power-of-two length.

Special care of index value must be taken into account. Index values out
of the table allocated space will crash Csound.


===========================================================================
tabifd                                                               *tabifd*

  Description

The tabifd opcode takes an input function table and performs an
Instantaneous Frequency, magnitude and phase analysis, using the STFT
and tabifd (Instantaneous Frequency Distribution), as described in
Lazzarini et al, "Time-stretching using the Instantaneous Frequency
Distribution and Partial Tracking", Proc.of ICMC05, Barcelona. It
generates two PV streaming signals, one containing the amplitudes and
frequencies (a similar output to pvsanal) and another containing
amplitudes and unwrapped phases.

  Syntax

ffr,fphs tabifd ktimpt, kamp, kpitch, ifftsize, ihopsize, iwintype,ifn

  Initialization

ifftsize -- FFT analysis size, must be power-of-two and integer multiple
of the hopsize.

ihopsize -- hopsize in samples

iwintype -- window type (O: Hamming, 1: Hanning)

ifn -- source function table

  Performance

ffr -- output pv stream in AMP_FREQ format

fphs -- output pv stream in AMP_PHASE format

ktimpt -- time point (in secs) to read from table (if less than 0 or
bigger than table length, it will wraparound)

kamp -- amplitude scaling

kpitch -- pitch scaling (transposition)


===========================================================================
table                                                                 *table*

  Description

Accesses table values by direct indexing.

  Syntax

ares table andx, ifn [, ixmode] [, ixoff] [, iwrap]

ires table indx, ifn [, ixmode] [, ixoff] [, iwrap]

kres table kndx, ifn [, ixmode] [, ixoff] [, iwrap]

  Initialization

ifn -- function table number.

ixmode (optional) -- index data mode. The default value is 0.

  * 0 = raw index

  * 1 = normalized (0 to 1)

ixoff (optional) -- amount by which index is to be offset. For a table
with origin at center, use tablesize/2 (raw) or .5 (normalized). The
default value is 0.

iwrap (optional) -- wraparound index flag. The default value is 0.

  * 0 = nowrap (index < 0 treated as index=0; index > tablesize sticks
    at index=size)

  * 1 = wraparound.

  Performance

table invokes table lookup on behalf of init, control or audio indices.
These indices can be raw entry numbers (0,l,2...size - 1) or scaled
values (0 to 1-e). Indices are first modified by the offset value then
checked for range before table lookup (see iwrap). If index is likely to
be full scale, or if interpolation is being used, the table should have
an extended guard point. table indexed by a periodic phasor ( see
phasor) will simulate an oscillator.


===========================================================================
table3                                                               *table3*

  Description

Accesses table values by direct indexing with cubic interpolation.

  Syntax

ares table3 andx, ifn [, ixmode] [, ixoff] [, iwrap]

ires table3 indx, ifn [, ixmode] [, ixoff] [, iwrap]

kres table3 kndx, ifn [, ixmode] [, ixoff] [, iwrap]

  Initialization

ifn -- function table number.

ixmode (optional) -- index data mode. The default value is 0.

  * 0 = raw index

  * 1 = normalized (0 to 1)

ixoff (optional) -- amount by which index is to be offset. For a table
with origin at center, use tablesize/2 (raw) or .5 (normalized). The
default value is 0.

iwrap (optional) -- wraparound index flag. The default value is 0.

  * 0 = nowrap (index < 0 treated as index=0; index > tablesize sticks
    at index=size)

  * 1 = wraparound.

  Performance

table3 is identical to tablei, except that it uses cubic interpolation.
(New in Csound version 3.50).


===========================================================================
tablecopy                                                         *tablecopy*

  Description

Simple, fast table copy opcode.

  Syntax

tablecopy kdft, ksft

  Performance

kdft -- Destination function table.

ksft -- Number of source function table.

tablecopy -- Simple, fast table copy opcode. Takes the table length from
the destination table, and reads from the start of the source table. For
speed reasons, does not check the source length - just copies regardless
- in “wrap” mode. This may read through the source table several times.
A source table with length 1 will cause all values in the destination
table to be written to its value.

tablecopy cannot read or write the guardpoint. To read it use table,
with ndx = the table length. Likewise use table write to write it.

To write the guardpoint to the value in location 0, use tablegpw.

This is primarily to change function tables quickly in a real-time
situation.


===========================================================================
tablefilter                                                     *tablefilter*

  Description

This opcode can be used in order to filter values from function tables
following certain algorithms. The filtered output is written into a
destination table and the number of elements that have passed the filter
is returned.

  Syntax

knumpassed tablefilter kouttable, kintatble, kmode, kparam

  Performance

knumpassed -- the number of elements that have passed the filter.

kouttable -- the number of the table containing the values that have
passed.

kintatble -- the number of the table used as filter input.

kmode -- mode of the filter:

  * 1 -- tests the weight of the denominators of the fractions in the
    source table. Letting pass only values from the source that are less
    heavy than the weight of the threshold.
  * 2 -- tests the weight of the denominators of the fractions in the
    source table. Letting pass only values from the source that are
    heavier than or equal to the weight of the threshold. 

kparam -- integer threshold parameter for the filter. It means that
denominators whose weights are heavier than the weight of this threshold
are not passed through the filter. The weight of an integer is
calculated using Clarence Barlow's function of indigestibility of a
number. According to this function, higher prime numbers contribute to
an increased weight of any natural integer they divide. The order of the
first 16 integers according to their indigestibility is: 1, 2, 4, 3, 8,
6, 16, 12, 9, 5, 10, 15, 7, 14.


===========================================================================
tablefilteri                                                   *tablefilteri*

  Description

This opcode can be used in order to filter values from function tables
following certain algorithms. The filtered output is written into a
destination table and the number of elements that have passed the filter
is returned.

  Syntax

inumpassed tablefilteri iouttable, iintatble, imode, iparam

  Initialization

inumpassed -- the number of elements that have passed the filter.

iouttable -- the number of the table containing the values that have
passed.

iintatble -- the number of the table used as filter input.

imode -- mode of the filter:

  * 1 -- tests the weight of the denominators of the fractions in the
    source table. Letting pass only values from the source that are less
    heavy than the weight of the threshold.
  * 2 -- tests the weight of the denominators of the fractions in the
    source table. Letting pass only values from the source that are
    heavier than or equal to the weight of the threshold. 

iparam -- integer threshold parameter for the filter. It means that
denominators whose weights are heavier than the weight of this threshold
are not passed through the filter. The weight of an integer is
calculated using Clarence Barlow's function of indigestibility of a
number. According to this function, higher prime numbers contribute to
an increased weight of any natural integer they divide. The order of the
first 16 integers according to their indigestibility is: 1, 2, 4, 3, 8,
6, 16, 12, 9, 5, 10, 15, 7, 14.


===========================================================================
tablegpw                                                           *tablegpw*

  Description

Writes a table's guard point.

  Syntax

tablegpw kfn

  Performance

kfn -- Table number to be interrogated

tablegpw -- For writing the table's guard point, with the value which is
in location 0. Does nothing if table does not exist.

Likely to be useful after manipulating a table with tablemix or tablecopy.


===========================================================================
tablei                                                               *tablei*

  Description

Accesses table values by direct indexing with linear interpolation.

  Syntax

ares tablei andx, ifn [, ixmode] [, ixoff] [, iwrap]

ires tablei indx, ifn [, ixmode] [, ixoff] [, iwrap]

kres tablei kndx, ifn [, ixmode] [, ixoff] [, iwrap]

  Initialization

ifn -- function table number. tablei requires the extended guard point.

ixmode (optional) -- index data mode. The default value is 0.

  * 0 = raw index

  * 1 = normalized (0 to 1)

ixoff (optional) -- amount by which index is to be offset. For a table
with origin at center, use tablesize/2 (raw) or .5 (normalized). The
default value is 0.

iwrap (optional) -- wraparound index flag. The default value is 0.

  * 0 = nowrap (index < 0 treated as index=0; index > tablesize sticks
    at index=size)

  * 1 = wraparound.

  Performance

tablei is a interpolating unit in which the fractional part of index is
used to interpolate between adjacent table entries. The smoothness
gained by interpolation is at some small cost in execution time (see
also oscili, etc.), but the interpolating and non-interpolating units
are otherwise interchangeable. Note that when tablei uses a periodic
index whose modulo n is less than the power of 2 table length, the
interpolation process requires that there be an (n + 1)th table value
that is a repeat of the 1st (see f Statement in score).


===========================================================================
tableicopy                                                       *tableicopy*

  Description

Simple, fast table copy opcode.

  Syntax

tableicopy idft, isft

  Initialization

idft -- Destination function table.

isft -- Number of source function table.

  Performance

tableicopy -- Simple, fast table copy opcodes. Takes the table length
from the destination table, and reads from the start of the source
table. For speed reasons, does not check the source length - just copies
regardless - in "wrap" mode. This may read through the source table
several times. A source table with length 1 will cause all values in the
destination table to be written to its value.

tableicopy cannot read or write the guardpoint. To read it use table,
with ndx = the table length. Likewise use table write to write it.

To write the guardpoint to the value in location 0, use tablegpw.

This is primarily to change function tables quickly in a real-time
situation.


===========================================================================
tableigpw                                                         *tableigpw*

  Description

Writes a table's guard point.

  Syntax

tableigpw ifn

  Initialization

ifn -- Table number to be interrogated

  Performance

tableigpw -- For writing the table's guard point, with the value which
is in location 0. Does nothing if table does not exist.

Likely to be useful after manipulating a table with tablemix or tablecopy.


===========================================================================
tableikt                                                           *tableikt*

  Description

k-rate control over table numbers. Function tables are read with linear
interpolation.

The standard Csound opcode tablei, when producing a k- or a-rate result,
can only use an init-time variable to select the table number. tableikt
accepts k-rate control as well as i-time. In all other respects they are
similar to the original opcodes.

  Syntax

ares tableikt xndx, kfn [, ixmode] [, ixoff] [, iwrap]

kres tableikt kndx, kfn [, ixmode] [, ixoff] [, iwrap]

  Initialization

ixmode -- if 0, xndx and ixoff ranges match the length of the table. if
non-zero xndx and ixoff have a 0 to 1 range. Default is 0

ixoff -- if 0, total index is controlled directly by xndx, ie. the
indexing starts from the start of the table. If non-zero, start indexing
from somewhere else in the table. Value must be positive and less than
the table length (ixmode = 0) or less than 1 (ixmode not equal to 0).
Default is 0.

iwrap -- if iwrap = 0, Limit mode: when total index is below 0, then
final index is 0.Total index above table length results in a final index
of the table length - high out of range total indexes stick at the upper
limit of the table. If iwrap not equal to 0, Wrap mode: total index is
wrapped modulo the table length so that all total indexes map into the
table. For instance, in a table of length 8, xndx = 5 and ixoff = 6
gives a total index of 11, which wraps to a final index of 3. Default is 0.

  Performance

kndx -- Index into table, either a positive number range matching the
table length (ixmode = 0) or a 0 to 1 range (ixmode not equal to 0).

xndx -- matching the table length (ixmode = 0) or a 0 to 1 range (ixmode
not equal to 0)

kfn -- Table number. Must be >= 1. Floats are rounded down to an
integer. If a table number does not point to a valid table, or the table
has not yet been loaded (GEN01) then an error will result and the
instrument will be de-activated.

[Caution]       Caution with k-rate table numbers

At k-rate, if a table number of < 1 is given, or the table number points
to a non-existent table, or to one which has a length of 0 (it is to be
loaded from a file later) then an error will result and the instrument
will be deactivated. kfn must be initialized at the appropriate rate
using init. Attempting to load an i-rate value into kfn will result in
an error.


===========================================================================
tableimix                                                         *tableimix*

  Description

Mixes two tables.

  Syntax

tableimix idft, idoff, ilen, is1ft, is1off, is1g, is2ft, is2off, is2g

  Initialization

idft -- Destination function table.

idoff -- Offset to start writing from. Can be negative.

ilen -- Number of write operations to perform. Negative means work
backwards.

is1ft, is2ft -- Source function tables. These can be the same as the
destination table, if care is exercised about direction of copying data.

is1off, is2off -- Offsets to start reading from in source tables.

is1g, is2g -- Gains to apply when reading from the source tables. The
results are added and the sum is written to the destination table.

  Performance

tableimix -- This opcode mixes from two tables, with separate gains into
the destination table. Writing is done for ilen locations, usually
stepping forward through the table - if ilen is positive. If it is
negative, then the writing and reading order is backwards - towards
lower indexes in the tables. This bi-directional option makes it easy to
shift the contents of a table sideways by reading from it and writing
back to it with a different offset.

If ilen is 0, no writing occurs. Note that the internal integer value of
ilen is derived from the ANSI C floor() function - which returns the
next most negative integer. Hence a fractional negative ilen value of
-2.3 would create an internal length of 3, and cause the copying to
start from the offset locations and proceed for two locations to the left.

The total index for table reading and writing is calculated from the
starting offset for each table, plus the index value, which starts at 0
and then increments (or decrements) by 1 as mixing proceeds.

These total indexes can potentially be very large, since there is no
restriction on the offset or the ilen. However each total index for each
table is ANDed with a length mask (such as 0000 0111 for a table of
length 8) to form a final index which is actually used for reading or
writing. So no reading or writing can occur outside the tables. This is
the same as “wrap” mode in table read and write. These opcodes do not
read or write the guardpoint. If a table has been rewritten with one of
these, then if it has a guardpoint which is supposed to contain the same
value as the location 0, then call tableigpw afterwards.

The indexes and offsets are all in table steps - they are not normalized
to 0 - 1. So for a table of length 256, ilen should be set to 256 if all
the table was to be read or written.

The tables do not need to be the same length - wrapping occurs
individually for each table.


===========================================================================
tableiw                                                             *tableiw*

  Description

This opcode operates on existing function tables, changing their
contents. tableiw is used when all inputs are init time variables or
constants and you only want to run it at the initialization of the
instrument. The valid combinations of variable types are shown by the
first letter of the variable names.

  Syntax

tableiw isig, indx, ifn [, ixmode] [, ixoff] [, iwgmode]

  Initialization

isig -- Input value to write to the table.

indx -- Index into table, either a positive number range matching the
table length (ixmode = 0) or a 0 to 1 range (ixmode not equal to 0)

ifn -- Table number. Must be >= 1. Floats are rounded down to an
integer. If a table number does not point to a valid table, or the table
has not yet been loaded (GEN01) then an error will result and the
instrument will be de-activated.

ixmode (optional, default=0) -- index mode.

  * 0 = indx and ixoff ranges match the length of the table.

  * not equal to 0 = indx and ixoff have a 0 to 1 range.

ixoff (optional, default=0) -- index offset.

  * 0 = Total index is controlled directly by indx, i.e. the indexing
    starts from the start of the table.

  * Not equal to 0 = Start indexing from somewhere else in the table.
    Value must be positive and less than the table length (ixmode = 0)
    or less than 1 (ixmode not equal to 0).

iwgmode (optional, default=0) -- Wrap and guard point mode.

  * 0 = Limit mode.

  * 1 = Wrap mode.

  * 2 = Guardpoint mode.

  Performance

      Limit mode (0)

Limit the total index (indx + ixoff) to between 0 and the guard point.
For a table of length 5, this means that locations 0 to 3 and location 4
(the guard point) can be written. A negative total index writes to
location 0.

      Wrap mode (1)

Wrap total index value into locations 0 to E, where E is either one less
than the table length or the factor of 2 number which is one less than
the table length. For example, wrap into a 0 to 3 range - so that total
index 6 writes to location 2.

      Guardpoint mode (2)

The guardpoint is written at the same time as location 0 is written -
with the same value.

This facilitates writing to tables which are intended to be read with
interpolation for producing smooth cyclic waveforms. In addition, before
it is used, the total index is incremented by half the range between one
location and the next, before being rounded down to the integer address
of a table location.

Normally (iwgmode = 0 or 1) for a table of length 5 - which has
locations 0 to 3 as the main table and location 4 as the guard point, a
total index in the range of 0 to 0.999 will write to location 0.
("0.999" means just less than 1.0.) 1.0 to 1.999 will write to location
1 etc. A similar pattern holds for all total indexes 0 to 4.999 (igwmode
= 0) or to 3.999 (igwmode = 1). igwmode = 0 enables locations 0 to 4 to
be written - with the guardpoint (4) being written with a potentially
different value from location 0.

With a table of length 5 and the iwgmode = 2, then when the total index
is in the range 0 to 0.499, it will write to locations 0 and 4. Range
0.5 to 1.499 will write to location 1 etc. 3.5 to 4.0 will also write to
locations 0 and 4.

This way, the writing operation most closely approximates the results of
interpolated reading. Guard point mode should only be used with tables
that have a guardpoint.

Guardpoint mode is accomplished by adding 0.5 to the total index,
rounding to the next lowest integer, wrapping it modulo the factor of
two which is one less than the table length, writing the table
(locations 0 to 3 in our example) and then writing to the guard point if
index = 0.


===========================================================================
tablekt                                                             *tablekt*

  Description

k-rate control over table numbers.

The standard Csound opcode table when producing a k- or a-rate result,
can only use an init-time variable to select the table number. tablekt
accepts k-rate control as well as i-time. In all other respects they are
similar to the original opcodes.

  Syntax

ares tablekt xndx, kfn [, ixmode] [, ixoff] [, iwrap]

kres tablekt kndx, kfn [, ixmode] [, ixoff] [, iwrap]

  Initialization

ixmode -- if 0, xndx and ixoff ranges match the length of the table. if
non-zero xndx and ixoff have a 0 to 1 range. Default is 0

ixoff -- if 0, total index is controlled directly by xndx, ie. the
indexing starts from the start of the table. If non-zero, start indexing
from somewhere else in the table. Value must be positive and less than
the table length (ixmode = 0) or less than 1 (ixmode not equal to 0).
Default is 0.

iwrap -- if iwrap = 0, Limit mode: when total index is below 0, then
final index is 0.Total index above table length results in a final index
of the table length - high out of range total indexes stick at the upper
limit of the table. If iwrap not equal to 0, Wrap mode: total index is
wrapped modulo the table length so that all total indexes map into the
table. For instance, in a table of length 8, xndx = 5 and ixoff = 6
gives a total index of 11, which wraps to a final index of 3. Default is 0.

  Performance

kndx -- Index into table, either a positive number range matching the
table length (ixmode = 0) or a 0 to 1 range (ixmode not equal to 0).

xndx -- matching the table length (ixmode = 0) or a 0 to 1 range (ixmode
not equal to 0)

kfn -- Table number. Must be >= 1. Floats are rounded down to an
integer. If a table number does not point to a valid table, or the table
has not yet been loaded (GEN01) then an error will result and the
instrument will be de-activated.

[Caution]       Caution with k-rate table numbers

At k-rate, if a table number of < 1 is given, or the table number points
to a non-existent table, or to one which has a length of 0 (it is to be
loaded from a file later) then an error will result and the instrument
will be deactivated. kfn must be initialized at the appropriate rate
using init. Attempting to load an i-rate value into kfn will result in
an error.


===========================================================================
tablemix                                                           *tablemix*

  Description

Mixes two tables.

  Syntax

tablemix kdft, kdoff, klen, ks1ft, ks1off, ks1g, ks2ft, ks2off, ks2g

  Performance

kdft -- Destination function table.

kdoff -- Offset to start writing from. Can be negative.

klen -- Number of write operations to perform. Negative means work
backwards.

ks1ft, ks2ft -- Source function tables. These can be the same as the
destination table, if care is exercised about direction of copying data.

ks1off, ks2off -- Offsets to start reading from in source tables.

ks1g, ks2g -- Gains to apply when reading from the source tables. The
results are added and the sum is written to the destination table.

tablemix -- This opcode mixes from two tables, with separate gains into
the destination table. Writing is done for klen locations, usually
stepping forward through the table - if klen is positive. If it is
negative, then the writing and reading order is backwards - towards
lower indexes in the tables. This bi-directional option makes it easy to
shift the contents of a table sideways by reading from it and writing
back to it with a different offset.

If klen is 0, no writing occurs. Note that the internal integer value of
klen is derived from the ANSI C floor() function - which returns the
next most negative integer. Hence a fractional negative klen value of
-2.3 would create an internal length of 3, and cause the copying to
start from the offset locations and proceed for two locations to the left.

The total index for table reading and writing is calculated from the
starting offset for each table, plus the index value, which starts at 0
and then increments (or decrements) by 1 as mixing proceeds.

These total indexes can potentially be very large, since there is no
restriction on the offset or the klen. However each total index for each
table is ANDed with a length mask (such as 0000 0111 for a table of
length 8) to form a final index which is actually used for reading or
writing. So no reading or writing can occur outside the tables. This is
the same as “wrap” mode in table read and write. These opcodes do not
read or write the guardpoint. If a table has been rewritten with one of
these, then if it has a guardpoint which is supposed to contain the same
value as the location 0, then call tablegpw afterwards.

The indexes and offsets are all in table steps - they are not normalized
to 0 - 1. So for a table of length 256, klen should be set to 256 if all
the table was to be read or written.

The tables do not need to be the same length - wrapping occurs
individually for each table.


===========================================================================
tableng                                                             *tableng*

  Description

Interrogates a function table for length.

  Syntax

ires tableng ifn

kres tableng kfn

  Initialization

ifn -- Table number to be interrogated

  Performance

kfn -- Table number to be interrogated

tableng returns the length of the specified table. This will be a power
of two number in most circumstances. It will not show whether a table
has a guardpoint or not. It seems this information is not available in
the table's data structure. If the specified table is not found, then 0
will be returned.

Likely to be useful for setting up code for table manipulation
operations, such as tablemix and tablecopy.


===========================================================================
tablera                                                             *tablera*

  Description

These opcode reads tables in sequential locations to an a-rate variable.
Some thought is required before using it. It has at least two major, and
quite different, applications which are discussed below.

  Syntax

ares tablera kfn, kstart, koff

  Performance

ares -- a-rate destination for reading ksmps values from a table.

kfn -- i- or k-rate number of the table to read or write.

kstart -- Where in table to read or write.

koff -- i- or k-rate offset into table. Range unlimited - see
explanation at end of this section.

In one application, tablera is intended to be used in pair with tablewa,
or with several tablera opcodes before a tablewa -- all sharing the same
kstart variable.

These read from and write to sequential locations in a table at audio
rates, with ksmps floats being written and read each cycle.

tablera starts reading from location kstart. tablewa starts writing to
location kstart, and then writes to kstart with the number of the
location one more than the one it last wrote. (Note that for tablewa,
kstart is both an input and output variable.) If the writing index
reaches the end of the table, then no further writing occurs and zero is
written to kstart.

For instance, if the table's length was 16 (locations 0 to 15), and
ksmps was 5. Then the following steps would occur with repetitive runs
of the tablewa opcode, assuming that kstart started at 0.

Run Number      Initial kstart  Final kstart    Locations Written
1       0       5       0 1 2 3 4
2       5       10      5 6 7 8 9
3       10      15      10 11 12 13 14
4       15      0       15

This is to facilitate processing table data using standard a-rate
orchestra code between the tablera and tablewaopcodes. They allow all
Csound k-rate operators to be used (with caution) on a-rate variables -
something that would only be possible otherwise by ksmps = 1, downsamp
and upsamp.

[Caution]       Several cautions

  * The k-rate code in the processing loop is really running at a-rate,
    so time dependent functions like port and oscil work faster than
    normal - their code is expecting to be running at k-rate.

  * This system will produce undesirable results unless the ksmps fits
    within the table length. For instance a table of length 16 will
    accommodate 1 to 16 samples, so this example will work with ksmps =
    1 to 16.

Both these opcodes generate an error and deactivate the instrument if a
table with length < ksmps is selected. Likewise an error occurs if
kstart is below 0 or greater than the highest entry in the table - if
kstart = table length.

  * kstart is intended to contain integer values between 0 and (table
    length - 1). Fractional values above this should not affect
    operation but do not achieve anything useful.

  * These opcodes are not interpolating, and the kstart and koff
    parameters always have a range of 0 to (table length - 1) - not 0 to
    1 as is available in other table read/write opcodes. koff can be
    outside this range but it is wrapped around by the final AND operation.

  * These opcodes are permanently in wrap mode. When koff is 0, no
    wrapping needs to occur, since the kstart++ index will always be
    within the table's normal range. koff not equal to 0 can lead to
    wrapping.

  * The offset does not affect the number of read/write cycles
    performed, or the value written to kstart by tablewa.

  * These opcodes cannot read or write the guardpoint. Use tablegpw to
    write the guardpoint after manipulations have been done with tablewa.


===========================================================================
tableseg                                                           *tableseg*

  Description

tableseg is like linseg but interpolate between values in a stored
function tables. The result is a new function table passed internally to
any following vpvoc which occurs before a subsequent tableseg (much like
lpread/lpreson pairs work). The uses of these are described below under
vpvoc.

  Syntax

tableseg ifn1, idur1, ifn2 [, idur2] [, ifn3] [...]

  Initialization

ifn1, ifn2, ifn3, etc. -- function table numbers. ifn1, ifn2, and so on,
must be the same size.

idur1, idur2, etc. -- durations during which interpolation from one
table to the next will take place.


===========================================================================
tableshuffle                                                   *tableshuffle*

  Description

This opcode can be used in order to shuffle the content of function
tables into a random order but without loosing any of the elements.
Imagine shuffling a deck of cards. Each element of the table is copied
to a different random position. If that position was already chosen
before then the next free position is chosen. The length of the table
remains the same.

  Syntax

tableshuffle ktablenum

tableshufflei itablenum

  Performance

ktablenum or itablenum -- the number of the table to shuffle.


===========================================================================
tablew                                                               *tablew*

  Description

This opcode operates on existing function tables, changing their
contents. tablew is for writing at k- or at a-rates, with the table
number being specified at init time. Using tablew with i-rate signal and
index values is allowed, but the specified data will always be written
to the function table at k-rate, not during the initialization pass. The
valid combinations of variable types are shown by the first letter of
the variable names.

  Syntax

tablew asig, andx, ifn [, ixmode] [, ixoff] [, iwgmode]

tablew isig, indx, ifn [, ixmode] [, ixoff] [, iwgmode]

tablew ksig, kndx, ifn [, ixmode] [, ixoff] [, iwgmode]

  Initialization

asig, isig, ksig -- The value to be written into the table.

andx, indx, kndx -- Index into table, either a positive number range
matching the table length (ixmode = 0) or a 0 to 1 range (ixmode != 0)

ifn -- Table number. Must be >= 1. Floats are rounded down to an
integer. If a table number does not point to a valid table, or the table
has not yet been loaded (GEN01) then an error will result and the
instrument will be de-activated.

ixmode (optional, default=0) -- index mode.

  * 0 = xndx and ixoff ranges match the length of the table.

  * !=0 = xndx and ixoff have a 0 to 1 range.

ixoff (optional, default=0) -- index offset.

  * 0 = Total index is controlled directly by xndx, i.e. the indexing
    starts from the start of the table.

  * !=0 = Start indexing from somewhere else in the table. Value must be
    positive and less than the table length (ixmode = 0) or less than 1
    (ixmode != 0).

iwgmode (optional, default=0) -- Wrap and guardpoint mode.

  * 0 = Limit mode.

  * 1 = Wrap mode.

  * 2 = Guardpoint mode.

  Performance

      Limit mode (0)

Limit the total index (ndx + ixoff) to between 0 and the guard point.
For a table of length 5, this means that locations 0 to 3 and location 4
(the guard point) can be written. A negative total index writes to
location 0.

      Wrap mode (1)

Wrap total index value into locations 0 to E, where E is either one less
than the table length or the factor of 2 number which is one less than
the table length. For example, wrap into a 0 to 3 range - so that total
index 6 writes to location 2.

      Guardpoint mode (2)

The guardpoint is written at the same time as location 0 is written -
with the same value.

This facilitates writing to tables which are intended to be read with
interpolation for producing smooth cyclic waveforms. In addition, before
it is used, the total index is incremented by half the range between one
location and the next, before being rounded down to the integer address
of a table location.

Normally (igwmode = 0 or 1) for a table of length 5 - which has
locations 0 to 3 as the main table and location 4 as the guard point, a
total index in the range of 0 to 0.999 will write to location 0.
("0.999" means just less than 1.0.) 1.0 to 1.999 will write to location
1 etc. A similar pattern holds for all total indexes 0 to 4.999 (igwmode
= 0) or to 3.999 (igwmode = 1). igwmode = 0 enables locations 0 to 4 to
be written - with the guardpoint (4) being written with a potentially
different value from location 0.

With a table of length 5 and the iwgmode = 2, then when the total index
is in the range 0 to 0.499, it will write to locations 0 and 4. Range
0.5 to 1.499 will write to location 1 etc. 3.5 to 4.0 will also write to
locations 0 and 4.

This way, the writing operation most closely approximates the results of
interpolated reading. Guard point mode should only be used with tables
that have a guardpoint.

Guardpoint mode is accomplished by adding 0.5 to the total index,
rounding to the next lowest integer, wrapping it modulo the factor of
two which is one less than the table length, writing the table
(locations 0 to 3 in our example) and then writing to the guard point if
index = 0.

tablew has no output value. The last three parameters are optional and
have default values of 0.

      Caution with k-rate table numbers

At k-rate or a-rate, if a table number of < 1 is given, or the table
number points to a non-existent table, or to one which has a length of 0
(it is to be loaded from a file later) then an error will result and the
instrument will be deactivated. kfn and afn must be initialized at the
appropriate rate using init. Attempting to load an i-rate value into kfn
or afn will result in an error.

  Warning

Note that tablew is always a k-rate opcode. This means that even its
i-rate version runs at k-rate and will write the value of the i-rate
variable. For this reason, the following code will not work as expected:

<CsoundSynthesizer>
<CsOptions>
</CsOptions>
<CsInstruments>
giFt ftgen  1, 0, 8, 2, 0
instr 1
indx = 0
     tablew 10, indx, giFt
ival tab_i  indx, giFt
     print  ival
endin
</CsInstruments>
<CsScore>
i 1 0 1
</CsScore>
</CsoundSynthesizer>

Although it may seem this program should print a 10 to the console. It
will print 0, because tab_i will read the value at the initialization of
the note, before the first performance pass, when tablew writes its value.


===========================================================================
tablewa                                                             *tablewa*

  Description

This opcode writes to a table in sequential locations to and from an
a-rate variable. Some thought is required before using it. It has at
least two major, and quite different, applications which are discussed
below.

  Syntax

kstart tablewa kfn, asig, koff

  Performance

kstart -- Where in table to read or write.

kfn -- i- or k-rate number of the table to read or write.

asig -- a-rate signal to read from when writing to the table.

koff -- i- or k-rate offset into table. Range unlimited - see
explanation at end of this section.

In one application, it is intended to be used with one or with several
tablera opcodes before a tablewa -- all sharing the same kstart variable.

These read from and write to sequential locations in a table at audio
rates, with ksmps floats being written and read each cycle.

tablera starts reading from location kstart. tablewa starts writing to
location kstart, and then writes to kstart with the number of the
location one more than the one it last wrote. (Note that for tablewa,
kstart is both an input and output variable.) If the writing index
reaches the end of the table, then no further writing occurs and zero is
written to kstart.

For instance, if the table's length was 16 (locations 0 to 15), and
ksmps was 5. Then the following steps would occur with repetitive runs
of the tablewa opcode, assuming that kstart started at 0.

Run Number      Initial kstart  Final kstart    Locations Written
1       0       5       0 1 2 3 4
2       5       10      5 6 7 8 9
3       10      15      10 11 12 13 14
4       15      0       15

This is to facilitate processing table data using standard a-rate
orchestra code between the tablera and tablewa opcodes. They allow all
Csound k-rate operators to be used (with caution) on a-rate variables -
something that would only be possible otherwise by ksmps = 1, downsamp
and upsamp.

[Caution]       Several cautions

  * The k-rate code in the processing loop is really running at a-rate,
    so time dependent functions like port and oscil work faster than
    normal - their code is expecting to be running at k-rate.

  * This system will produce undesirable results unless the ksmps fits
    within the table length. For instance a table of length 16 will
    accommodate 1 to 16 samples, so this example will work with ksmps =
    1 to 16.

Both these opcodes generate an error and deactivate the instrument if a
table with length < ksmps is selected. Likewise an error occurs if
kstart is below 0 or greater than the highest entry in the table - if
kstart = table length.

  * kstart is intended to contain integer values between 0 and (table
    length - 1). Fractional values above this should not affect
    operation but do not achieve anything useful.

  * These opcodes are not interpolating, and the kstart and koff
    parameters always have a range of 0 to (table length - 1) - not 0 to
    1 as is available in other table read/write opcodes. koff can be
    outside this range but it is wrapped around by the final AND operation.

  * These opcodes are permanently in wrap mode. When koff is 0, no
    wrapping needs to occur, since the kstart++ index will always be
    within the table's normal range. koff not equal to 0 can lead to
    wrapping.

  * The offset does not affect the number of read/write cycles
    performed, or the value written to kstart by tablewa.

  * These opcodes cannot read or write the guardpoint. Use tablegpw to
    write the guardpoint after manipulations have been done with tablewa.


===========================================================================
tablewkt                                                           *tablewkt*

  Description

This opcode operates on existing function tables, changing their
contents. tablewkt uses a k-rate variable for selecting the table
number. The valid combinations of variable types are shown by the first
letter of the variable names.

  Syntax

tablewkt asig, andx, kfn [, ixmode] [, ixoff] [, iwgmode]

tablewkt ksig, kndx, kfn [, ixmode] [, ixoff] [, iwgmode]

  Initialization

asig, ksig -- The value to be written into the table.

andx, kndx -- Index into table, either a positive number range matching
the table length (ixmode = 0) or a 0 to 1 range (ixmode != 0)

kfn -- Table number. Must be >= 1. Floats are rounded down to an
integer. If a table number does not point to a valid table, or the table
has not yet been loaded (GEN01) then an error will result and the
instrument will be de-activated.

ixmode -- index mode. Default is zero.

  * 0 = xndx and ixoff ranges match the length of the table.

  * Not equal to 0 = xndx and ixoff have a 0 to 1 range.

ixoff -- index offset. Default is 0.

  * 0 = Total index is controlled directly by xndx, i.e. the indexing
    starts from the start of the table.

  * Not equal to 0 = Start indexing from somewhere else in the table.
    Value must be positive and less than the table length (ixmode = 0)
    or less than 1 (ixmode != 0).

iwgmode -- table writing mode. Default is 0.

  * 0 = Limit mode.

  * 1 = Wrap mode.

  * 2 = Guardpoint mode.

  Performance

      Limit mode (0)

Limit the total index (ndx + ixoff) to between 0 and the guard point.
For a table of length 5, this means that locations 0 to 3 and location 4
(the guard point) can be written. A negative total index writes to
location 0.

      Wrap mode (1)

Wrap total index value into locations 0 to E, where E is one less than
either the table length or the factor of 2 number which is one less than
the table length. For example, wrap into a 0 to 3 range - so that total
index 6 writes to location 2.

      Guardpoint mode (2)

The guardpoint is written at the same time as location 0 is written -
with the same value.

This facilitates writing to tables which are intended to be read with
interpolation for producing smooth cyclic waveforms. In addition, before
it is used, the total index is incremented by half the range between one
location and the next, before being rounded down to the integer address
of a table location.

Normally (igwmode = 0 or 1) for a table of length 5 - which has
locations 0 to 3 as the main table and location 4 as the guard point, a
total index in the range of 0 to 0.999 will write to location 0.
("0.999" means just less than 1.0.) 1.0 to 1.999 will write to location
1 etc. A similar pattern holds for all total indexes 0 to 4.999 (igwmode
= 0) or to 3.999 (igwmode = 1). igwmode = 0 enables locations 0 to 4 to
be written - with the guardpoint (4) being written with a potentially
different value from location 0.

With a table of length 5 and the iwgmode = 2, then when the total index
is in the range 0 to 0.499, it will write to locations 0 and 4. Range
0.5 to 1.499 will write to location 1 etc. 3.5 to 4.0 will also write to
locations 0 and 4.

This way, the writing operation most closely approximates the results of
interpolated reading. Guard point mode should only be used with tables
that have a guardpoint.

Guardpoint mode is accomplished by adding 0.5 to the total index,
rounding to the next lowest integer, wrapping it modulo the factor of
two which is one less than the table length, writing the table
(locations 0 to 3 in our example) and then writing to the guard point if
index = 0.

      Caution with k-rate table numbers

At k-rate or a-rate, if a table number of < 1 is given, or the table
number points to a non-existent table, or to one which has a length of 0
(it is to be loaded from a file later) then an error will result and the
instrument will be deactivated. kfn and afn must be initialized at the
appropriate rate using init. Attempting to load an i-rate value into kfn
or afn will result in an error.


===========================================================================
tablexkt                                                           *tablexkt*

  Description

Reads function tables with linear, cubic, or sinc interpolation.

  Syntax

ares tablexkt xndx, kfn, kwarp, iwsize [, ixmode] [, ixoff] [, iwrap]

  Initialization

iwsize -- This parameter controls the type of interpolation to be used:

  * 2: Use linear interpolation. This is the lowest quality, but also
    the fastest mode.

  * 4: Cubic interpolation. Slightly better quality than iwsize = 2, at
    the expense of being somewhat slower.

  * 8 and above (up to 1024): sinc interpolation with window size set to
    iwsize (should be an integer multiply of 4). Better quality than
    linear or cubic interpolation, but very slow. When transposing up, a
    kwarp value above 1 can be used for anti-aliasing (this is even slower).

ixmode1 (optional) -- index data mode. The default value is 0.

  * 0: raw index

  * any non-zero value: normalized (0 to 1)

  Notes

if tablexkt is used to play back samples with looping (e.g. table index
is generated by lphasor), there must be at least iwsize / 2 extra
samples after the loop end point for interpolation, otherwise audible
clicking may occur (also, at least iwsize / 2 samples should be before
the loop start point).

ixoff (optional) -- amount by which index is to be offset. For a table
with origin at center, use tablesize / 2 (raw) or 0.5 (normalized). The
default value is 0.

iwrap (optional) -- wraparound index flag. The default value is 0.

  * 0: Nowrap (index < 0 treated as index = 0; index >= tablesize (or
    1.0 in normalized mode) sticks at the guard point).

  * any non-zero value: Index is wrapped to the allowed range (not
    including the guard point in this case).

  Note

iwrap also applies to extra samples for interpolation.

  Performance

ares -- audio output

xndx -- table index

kfn -- function table number

kwarp -- if greater than 1, use sin (x / kwarp) / x function for sinc
interpolation, instead of the default sin (x) / x. This is useful to
avoid aliasing when transposing up (kwarp should be set to the transpose
factor in this case, e.g. 2.0 for one octave), however it makes
rendering up to twice as slow. Also, iwsize should be at least kwarp *
8. This feature is experimental, and may be optimized both in terms of
speed and quality in new versions.

  Note

kwarp has no effect if it is less than, or equal to 1, or linear or
cubic interpolation is used.


===========================================================================
tablexseg                                                         *tablexseg*

  Description

tablexseg is like expseg but interpolate between values in a stored
function tables. The result is a new function table passed internally to
any following vpvoc which occurs before a subsequent tablexseg (much
like lpread/lpreson pairs work). The uses of these are described below
under vpvoc.

  Syntax

tablexseg ifn1, idur1, ifn2 [, idur2] [, ifn3] [...]

  Initialization

ifn1, ifn2, ifn3, etc. -- function table numbers. ifn1, ifn2, and so on,
must be the same size.

idur1, idur2, etc. -- durations during which interpolation from one
table to the next will take place.


===========================================================================
tabmorph                                                           *tabmorph*

  Description

tabmorph allows morphing between a set of tables of the same size, by
means of a weighted average between two currently selected tables.

  Syntax

kout tabmorph kindex, kweightpoint, ktabnum1, ktabnum2, \
      ifn1, ifn2 [, ifn3, ifn4, ...,ifnN]

  Initialization

ifn1, ifn2 [, ifn3, ifn4, ..., ifnN] - function table numbers. This is a
set of chosen tables the user want to use in the morphing. All tables
must have the same length. Be aware that only two of these tables can be
chosen for the morphing at one time. Since it is possible to use
non-integer numbers for the ktabnum1 and ktabnum2 arguments, the
morphing is the result from the interpolation between adjacent
consecutive tables of the set.

  Performance

kout - The output value for index kindex, resulting from morphing two
tables (see below).

kindex - main index of the morphed resultant table. The range is 0 to
table_length (not included).

kweightpoint - the weight of the influence of a pair of selected tables
in the morphing. The range of this argument is 0 to 1. A zero makes it
output the first table unaltered, a 1 makes it output the second table
of the pair unaltered. All intermediate values between 0 and 1 determine
the gradual morphing between the two tables of the pair.

ktabnum1 - the first table chosen for the morphing. This number doesn’t
express the table number directly, but the position of the table in the
set sequence (starting from 0 to N-1). If this number is an integer, the
corresponding table will be chosen unaltered. If it contains fractional
values, then an interpolation with the next adjacent table will result.

ktabnum2 - the second table chosen for the morphing. This number doesn’t
express the table number directly, but the position of the table in the
set sequence (starting from 0 to N-1). If this number is an integer,
corresponding table will be chosen unaltered. If it contains fractional
values, then an interpolation with the next adjacent table will result.

The tabmorph family of opcodes is similar to the table family, but
allows morphing between two tables chosen into a set of tables. Firstly
the user has to provide a set of tables of equal length (ifn2 [, ifn3,
ifn4, ..., ifnN]). Then he can choose a pair of tables in the set in
order to perform the morphing: ktabnum1 and ktabnum2 are filled with
numbers (zero represents the first table in the set, 1 the second, 2 the
third and so on). Then determine the morphing between the two chosen
tables with the kweightpoint parameter. After that the resulting table
can be indexed with the kindex parameter like a normal table opcode. If
the value of this parameter surpasses the length of tables (which must
be the same for all tables), then it is wrapped around.

tabmorph acts similarly to the table opcode, that is, without using
interpolation. This means that it truncates the fractional part of the
kindex argument. Anyway, fractional parts of ktabnum1 and ktabnum2 are
significant, resulting in linear interpolation between the same element
of two adjacent subsequent tables.


===========================================================================
tabmorpha                                                         *tabmorpha*

  Description

tabmorpha allows morphing between a set of tables of the same size, by
means of a weighted average between two currently selected tables.

  Syntax

aout tabmorpha aindex, aweightpoint, atabnum1, atabnum2, \
      ifn1, ifn2 [, ifn3, ifn4, ... ifnN]

  Initialization

ifn1, ifn2 , ifn3, ifn4, ... ifnN - function table numbers. This is a
set of chosen tables the user want to use in the morphing. All tables
must have the same length. Be aware that only two of these tables can be
chosen for the morphing at one time. Since it is possible to use
non-integer numbers for the atabnum1 and atabnum2 arguments, the
morphing is the result from the interpolation between adjacent
consecutive tables of the set.

  Performance

aout - The output value for index aindex, resulting from morphing two
tables (see below).

aindex - main index index of the morphed resultant table. The range is 0
to table_length (not included).

aweightpoint - the weight of the influence of a pair of selected tables
in the morphing. The range of this argument is 0 to 1. A zero makes it
output the first table unaltered, a 1 makes it output the second table
of the pair unaltered. All intermediate values between 0 and 1 determine
the gradual morphing between the two tables of the pair.

atabnum1 - the first table chosen for the morphing. This number doesn’t
express the table number directly, but the position of the table in the
set sequence (starting from 0 to N-1). If this number is an integer, the
corresponding table will be chosen unaltered. If it contains fractional
values, then an interpolation with the next adjacent table will result.

atabnum2 - the second table chosen for the morphing. This number doesn’t
express the table number directly, but the position of the table in the
set sequence (starting from 0 to N-1). If this number is an integer,
corresponding table will be chosen unaltered. If it contains fractional
values, then an interpolation with the next adjacent table will result.

The tabmorpha family of opcodes is similar to the table family, but
allows morphing between two tables chosen into a set of tables. Firstly
the user has to provide a set of tables of equal length (ifn2 [, ifn3,
ifn4,…ifnN]). Then he can choose a pair of tables in the set in order to
perform the morphing: atabnum1 and atabnum2 are filled with numbers
(zero represents the first table in the set, 1 the second, 2 the third
and so on). Then determine the morphing between the two chosen tables
with the aweightpoint parameter. After that the resulting table can be
indexed with the aindex parameter like a normal table opcode. If the
value of this parameter surpasses the length of tables (which must be
the same for all tables), then it is wrapped around.

tabmorpha is the audio-rate version of tabmorphi (it uses
interpolation). All input arguments work at a-rate.


===========================================================================
tabmorphak                                                       *tabmorphak*

  Description

tabmorphak allows morphing between a set of tables of the same size, by
means of a weighted average between two currently selected tables.

  Syntax

aout tabmorphak aindex, kweightpoint, ktabnum1, ktabnum2, \
      ifn1, ifn2 [, ifn3, ifn4, ... ifnN]

  Initialization

ifn1, ifn2 , ifn3, ifn4, ... ifnN - function table numbers. This is a
set of chosen tables the user want to use in the morphing. All tables
must have the same length. Be aware that only two of these tables can be
chosen for the morphing at one time. Since it is possible to use
non-integer numbers for the ktabnum1 and ktabnum2 arguments, the
morphing is the result from the interpolation between adjacent
consecutive tables of the set.

  Performance

aout - The output value for index aindex, resulting from morphing two
tables (see below).

aindex - main index index of the morphed resultant table. The range is 0
to table_length (not included).

kweightpoint - the weight of the influence of a pair of selected tables
in the morphing. The range of this argument is 0 to 1. A zero makes it
output the first table unaltered, a 1 makes it output the second table
of the pair unaltered. All intermediate values between 0 and 1 determine
the gradual morphing between the two tables of the pair.

ktabnum1 - the first table chosen for the morphing. This number doesn’t
express the table number directly, but the position of the table in the
set sequence (starting from 0 to N-1). If this number is an integer, the
corresponding table will be chosen unaltered. If it contains fractional
values, then an interpolation with the next adjacent table will result.

ktabnum2 - the second table chosen for the morphing. This number doesn’t
express the table number directly, but the position of the table in the
set sequence (starting from 0 to N-1). If this number is an integer,
corresponding table will be chosen unaltered. If it contains fractional
values, then an interpolation with the next adjacent table will result.

The tabmorphak family of opcodes is similar to the table family, but
allows morphing between two tables chosen into a set of tables. Firstly
the user has to provide a set of tables of equal length (ifn2 [, ifn3,
ifn4, ... ifnN]). Then he can choose a pair of tables in the set in
order to perform the morphing: ktabnum1 and ktabnum2 are filled with
numbers (zero represents the first table in the set, 1 the second, 2 the
third and so on). Then determine the morphing between the two chosen
tables with the kweightpoint parameter. After that the resulting table
can be indexed with the aindex parameter like a normal table opcode. If
the value of this parameter surpasses the length of tables (which must
be the same for all tables), then it is wrapped around.

tabmorphak works at a-rate, but kweightpoint, ktabnum1 and ktabnum2 are
working at k-rate, making it more efficient than tabmorpha, since there
are less calculations. Except the rate of these three arguments, it is
identical to tabmorpha.


===========================================================================
tabmorphi                                                         *tabmorphi*

  Description

tabmorphi allows morphing between a set of tables of the same size, by
means of a weighted average between two currently selected tables.

  Syntax

kout tabmorphi kindex, kweightpoint, ktabnum1, ktabnum2, \
      ifn1, ifn2 [, ifn3, ifn4, ..., ifnN]

  Initialization

ifn1, ifn2 [, ifn3, ifn4, ..., ifnN] - function table numbers. This is a
set of chosen tables the user want to use in the morphing. All tables
must have the same length. Be aware that only two of these tables can be
chosen for the morphing at one time. Since it is possible to use
non-integer numbers for the ktabnum1 and ktabnum2 arguments, the
morphing is the result from the interpolation between adjacent
consecutive tables of the set.

  Performance

kout - The output value for index kindex, resulting from morphing two
tables (see below).

kindex - main index index of the morphed resultant table. The range is 0
to table_length (not included).

kweightpoint - the weight of the influence of a pair of selected tables
in the morphing. The range of this argument is 0 to 1. A zero makes it
output the first table unaltered, a 1 makes it output the second table
of the pair unaltered. All intermediate values between 0 and 1 determine
the gradual morphing between the two tables of the pair.

ktabnum1 - the first table chosen for the morphing. This number doesn’t
express the table number directly, but the position of the table in the
set sequence (starting from 0 to N-1). If this number is an integer, the
corresponding table will be chosen unaltered. If it contains fractional
values, then an interpolation with the next adjacent table will result.

ktabnum2 - the second table chosen for the morphing. This number doesn’t
express the table number directly, but the position of the table in the
set sequence (starting from 0 to N-1). If this number is an integer,
corresponding table will be chosen unaltered. If it contains fractional
values, then an interpolation with the next adjacent table will result.

The tabmorphi family of opcodes is similar to the table family, but
allows morphing between two tables chosen into a set of tables. Firstly
the user has to provide a set of tables of equal length (ifn2 [, ifn3,
ifn4, ..., ifnN]). Then he can choose a pair of tables in the set in
order to perform the morphing: ktabnum1 and ktabnum2 are filled with
numbers (zero represents the first table in the set, 1 the second, 2 the
third and so on). Then determine the morphing between the two chosen
tables with the kweightpoint parameter. After that the resulting table
can be indexed with the kindex parameter like a normal table opcode. If
the value of this parameter surpasses the length of tables (which must
be the same for all tables), then it is wrapped around.

tabmorphi is identical to tabmorph, but it performs linear interpolation
for non-integer values of kindex, much like tablei.


===========================================================================
tabplay                                                             *tabplay*

  Description

Plays-back control-rate signals on trigger-temporization basis.

  Syntax

tabplay  ktrig, knumtics, kfn, kout1 [,kout2,..., koutN]

  Performance

ktrig -- starts playing when non-zero.

knumtics -- stop recording or reset playing pointer to zero when the
number of tics defined by this argument is reached.

kfn -- table where k-rate signals are recorded.

kout1,...,koutN -- playback output signals.

The tabplay and tabrec opcodes allow to record/playback control signals
on trigger-temporization basis.

tabplay plays back a group of k-rate signals, previously recorded by
tabrec into a table. Each time ktrig argument is triggered, an internal
counter is increased of one unit. After knumtics trigger impluses are
received by ktrig argument, the internal counter is zeroed and playback
is restarted from the beginning, in looping style.

These opcodes can be used like a sort of ``middle-term'' memory that
``remembers'' generated signals. Such memory can be used to supply
generative music with a coherent iterative compositional structure.


===========================================================================
tabrec                                                               *tabrec*

  Description

Records control-rate signals on trigger-temporization basis.

  Syntax

tabrec   ktrig_start, ktrig_stop, knumtics, kfn, kin1 [,kin2,...,kinN]

  Performance

ktrig_start -- start recording when non-zero.

ktrig_stop -- stop recording when knumtics trigger impulses are received
by this input argument.

knumtics -- stop recording or reset playing pointer to zero when the
number of tics defined by this argument is reached.

kfn -- table where k-rate signals are recorded.

kin1,...,kinN -- input signals to record.

The tabrec and tabplay opcodes allow to record/playback control signals
on trigger-temporization basis.

tabrec opcode records a group of k-rate signals by storing them into kfn
table. Each time ktrig_start is triggered, tabrec resets the table
pointer to zero and begins to record. Recording phase stops after
knumtics trigger impulses have been received by ktrig_stop argument.

These opcodes can be used like a sort of ``middle-term'' memory that
``remembers'' generated signals. Such memory can be used to supply
generative music with a coherent iterative compositional structure.


===========================================================================
tabsum                                                               *tabsum*

  Description

Sums the values in an f-table in a consecutive range.

  Syntax

kr tabsum ifn[[, kmin] [, kmax]]

  Initialization

ifn -- table number

  Performance

kr -- input signal to write.

kmin, kmax -- range of the table to sum. If omitted or zero they default
to 0 to length of the table.


===========================================================================
tab2pvs                                                             *tab2pvs*

  Description

Copies a pvs frame from a t-variable or k-rate array. Currently only
AMP+FREQ is produced. This opcode requires the t-type to be defined,
which means it only works in the new bison/flex-based parser.

  Syntax

fsig tab2pvs tvar|karr[][,ihopsize, iwinsize, iwintype]

  Performance

tvar -- k-rate array (or t-variable) containing the input. It is
produced at every k-period, but may not contain a new frame, pvs frames
are produced at their own frame rate that is independent of kr. The size
of this vector will determine the fftsize, N = size - 2.

fsig -- output fsig to be copied.

iolap -- size of the analysis overlap, defaults to isize/4.

iwinsize -- size of the analysis window, defaults to isize.

iwintype -- type of analysis window, defaults to 1, Hanning.


===========================================================================
tambourine                                                       *tambourine*

  Description

tambourine is a semi-physical model of a tambourine sound. It is one of
the PhISEM percussion opcodes. PhISEM (Physically Informed Stochastic
Event Modeling) is an algorithmic approach for simulating collisions of
multiple independent sound producing objects.

  Syntax

ares tambourine kamp, idettack [, inum] [, idamp] [, imaxshake] [, ifreq] \
      [, ifreq1] [, ifreq2]

  Initialization

idettack -- period of time over which all sound is stopped

inum (optional) -- The number of beads, teeth, bells, timbrels, etc. If
zero, the default value is 32.

idamp (optional) -- the damping factor, as part of this equation:

damping_amount = 0.9985 + (idamp * 0.002)

The default damping_amount is 0.9985 which means that the default value
of idamp is 0. The maximum damping_amount is 1.0 (no damping). This
means the maximum value for idamp is 0.75.

The recommended range for idamp is usually below 75% of the maximum value.

imaxshake (optional, default=0) -- amount of energy to add back into the
system. The value should be in range 0 to 1.

ifreq (optional) -- the main resonant frequency. The default value is 2300.

ifreq1 (optional) -- the first resonant frequency. The default value is
5600.

ifreq2 (optional) -- the second resonant frequency. The default value is
8100.

  Performance

kamp -- Amplitude of output. Note: As these instruments are stochastic,
this is only an approximation.


===========================================================================
tan                                                                     *tan*

  Description

Returns the tangent of x (x in radians).

  Syntax

tan(x) (no rate restriction)


===========================================================================
tanh                                                                   *tanh*

  Description

Returns the hyperbolic tangent of x.

  Syntax

tanh(x) (no rate restriction)


===========================================================================
taninv                                                               *taninv*

  Description

Returns the arctangent of x (x in radians).

  Syntax

taninv(x) (no rate restriction)


===========================================================================
taninv2                                                             *taninv2*

  Description

Returns the arctangent of iy/ix, ky/kx, or ay/ax.

  Syntax

ares taninv2 ay, ax

ires taninv2 iy, ix

kres taninv2 ky, kx

...taninv2(ky, kx)... (no rate restriction)

Returns the arctangent of iy/ix, ky/kx, or ay/ax. If y is zero, taninv2
returns zero regardless of the value of x. If x is zero, the return
value is:

  * π/2, if y is positive.

  * -π/2, if y is negative.

  * 0, if y is 0.

  Initialization

iy, ix -- values to be converted

  Performance

ky, kx -- control rate signals to be converted

ay, ax -- audio rate signals to be converted


===========================================================================
tbvcf                                                                 *tbvcf*

  Description

This opcode attempts to model some of the filter characteristics of a
Roland TB303 voltage-controlled filter. Euler's method is used to
approximate the system, rather than traditional filter methods. Cutoff
frequency, Q, and distortion are all coupled. Empirical methods were
used to try to unentwine, but frequency is only approximate as a result.
Future fixes for some problems with this opcode may break existing
orchestras relying on this version of tbvcf.

  Syntax

ares tbvcf asig, xfco, xres, kdist, kasym [, iskip]

  Initialization

iskip (optional, default=0) -- if non zero skip the initialisation of
the filter. (New in Csound version 4.23f13 and 5.0)

  Performance

asig -- input signal. Should be normalized to ±1.

xfco -- filter cutoff frequency. Optimum range is 10,000 to 1500. Values
below 1000 may cause problems.

xres -- resonance or Q. Typically in the range 0 to 2.

kdist -- amount of distortion. Typical value is 2. Changing kdist
significantly from 2 may cause odd interaction with xfco and xres.

kasym -- asymmetry of resonance. Typically in the range 0 to 1.


===========================================================================
tempest                                                             *tempest*

  Description

Estimate the tempo of beat patterns in a control signal.

  Syntax

ktemp tempest kin, iprd, imindur, imemdur, ihp, ithresh, ihtim, ixfdbak, \
      istartempo, ifn [, idisprd] [, itweek]

  Initialization

iprd -- period between analyses (in seconds). Typically about .02 seconds.

imindur -- minimum duration (in seconds) to serve as a unit of tempo.
Typically about .2 seconds.

imemdur -- duration (in seconds) of the kin short-term memory buffer
which will be scanned for periodic patterns. Typically about 3 seconds.

ihp -- half-power point (in Hz) of a low-pass filter used to smooth
input kin prior to other processing. This will tend to suppress activity
that moves much faster. Typically 2 Hz.

ithresh -- loudness threshold by which the low-passed kin is
center-clipped before being placed in the short-term buffer as
tempo-relevant data. Typically at the noise floor of the incoming data.

ihtim -- half-time (in seconds) of an internal forward-masking filter
that masks new kin data in the presence of recent, louder data.
Typically about .005 seconds.

ixfdbak -- proportion of this unit's anticipated value to be mixed with
the incoming kin prior to all processing. Typically about .3.

istartempo -- initial tempo (in beats per minute). Typically 60.

ifn -- table number of a stored function (drawn left-to-right) by which
the short-term memory data is attenuated over time.

idisprd (optional) -- if non-zero, display the short-term past and
future buffers every idisprd seconds (normally a multiple of iprd). The
default value is 0 (no display).

itweek (optional) -- fine-tune adjust this unit so that it is stable
when analyzing events controlled by its own output. The default value is
1 (no change).

  Performance

tempest examines kin for amplitude periodicity, and estimates a current
tempo. The input is first low-pass filtered, then center-clipped, and
the residue placed in a short-term memory buffer (attenuated over time)
where it is analyzed for periodicity using a form of autocorrelation.
The period, expressed as a tempo in beats per minute, is output as
ktemp. The period is also used internally to make predictions about
future amplitude patterns, and these are placed in a buffer adjacent to
that of the input. The two adjacent buffers can be periodically
displayed, and the predicted values optionally mixed with the incoming
signal to simulate expectation.

This unit is useful for sensing the metric implications of any k-signal
(e.g.- the RMS of an audio signal, or the second derivative of a
conducting gesture), before sending to a tempo statement.


===========================================================================
tempo                                                                 *tempo*

  Description

Apply tempo control to an uninterpreted score.

  Syntax

tempo ktempo, istartempo

  Initialization

istartempo -- initial tempo (in beats per minute). Typically 60.

  Performance

ktempo -- The tempo to which the score will be adjusted.

tempo allows the performance speed of Csound scored events to be
controlled from within an orchestra. It operates only in the presence of
the Csound -t flag. When that flag is set, scored events will be
performed from their uninterpreted p2 and p3 (beat) parameters,
initially at the given command-line tempo. When a tempo statement is
activated in any instrument (ktempo 0.), the operating tempo will be
adjusted to ktempo beats per minute. There may be any number of tempo
statements in an orchestra, but coincident activation is best avoided.


===========================================================================
temposcal                                                         *temposcal*

  Description

temposcal implements phase-locked vocoder processing using function
tables containing sampled-sound sources, with GEN01, and temposcal will
accept deferred allocation tables.

This opcode allows for time and frequency-independent scaling. Time is
advanced internally, but controlled by a tempo scaling parameter; when
an onset is detected, timescaling is momentarily stopped to avoid
smearing of attacks. The quality of the effect is generally improved
with phase locking switched on.

temposcal will also scale pitch, independently of frequency, using a
transposition factor (k-rate).

  Syntax

asig temposcal ktimescal, kamp, kpitch, ktab, klock [,ifftsize, idecim, ithresh]

  Initialization

ifftsize -- FFT size (power-of-two), defaults to 2048.

idecim -- decimation, defaults to 4 (meaning hopsize = fftsize/4)

idbthresh -- threshold based on dB power spectrum ratio between two
successive windows. A detected ratio above it will cancel timescaling
momentarily, to avoid smearing (defaults to 1)

  Performance

ktimescal -- timescaling ratio, < 1 stretch, > 1 contract.

kamp -- amplitude scaling

kpitch -- grain pitch scaling (1=normal pitch, < 1 lower, > 1 higher;
negative, backwards)

klock -- 0 or 1, to switch phase-locking on/off

ktab -- source signal function table. Deferred-allocation tables (see
GEN01) are accepted, but the opcode expects a mono source. Tables can be
switched at k-rate.


===========================================================================
tempoval                                                           *tempoval*

  Description

Reads the current value of the tempo.

  Syntax

kres tempoval

  Performance

kres -- the value of the tempo. If you use a positive value with the -t
command-line flag, tempoval returns the percentage increase/decrease
from the original tempo of 60 beats per minute. If you don't, its value
will be 60 (for 60 beats per minute).


===========================================================================
tigoto                                                               *tigoto*

  Description

Similar to igoto but effective only during an i-time pass at which a new
note is being “tied” onto a previously held note. (See i Statement) It
does not work when a tie has not taken place. Allows an instrument to
skip initialization of units according to whether a proposed tie was in
fact successful. (See also tival).

  Syntax

tigoto label

where label is in the same instrument block and is not an expression.


===========================================================================
timedseq                                                           *timedseq*

  Description

An event-sequencer in which time can be controlled by a time-pointer.
Sequence data are stored into a table.

  Syntax

ktrig  timedseq  ktimpnt, ifn, kp1 [,kp2, kp3, ...,kpN]

  Initialization

ifn -- number of table containing sequence data.

  Performance

ktri -- output trigger signal

ktimpnt -- time pointer into sequence file, in seconds.

kp1,...,kpN -- output p-fields of notes. kp2 meaning is relative action
time and kp3 is the duration of notes in seconds.

timedseq is a sequencer that allows to schedule notes starting from a
user sequence, and depending from an external timing given by a
time-pointer value (ktimpnt argument). User should fill table ifn with a
list of notes, that can be provided in an external text file by using
GEN23, or by typing it directly in the orchestra (or score) file with
GEN02. The format of the text file containing the sequence is made up
simply by rows containing several numbers separated by space (similarly
to normal Csound score). The first value of each row must be a positive
or null value, except for a special case that will be explained below.
This first value is normally used to define the instrument number
corresponding to that particular note (like normal score). The second
value of each row must contain the action time of corresponding note and
the third value its duration. This is an example:

0 0    0.25 1  93
0 0.25 0.25 2  63
0 0.5  0.25 3  91
0 0.75 0.25 4  70
0 1    0.25 5  83
0 1.25 0.25 6  75
0 1.5  0.25 7  78
0 1.75 0.25 8  78
0 2    0.25 9  83
0 2.25 0.25 10 70
0 2.5  0.25 11 54
0 2.75 0.25 12 80
-1 3   -1   -1 -1  ;; last row of the sequence

In this example, the first value of each row is always zero (it is a
dummy value, but this p-field can be used, for example, to express a
MIDI channel or an instrument number), except the last row, that begins
with -1. This value (-1) is a special value, that indicates the end of
sequence. It has itself an action time, because sequences can be looped.
So the previous sequence has a default duration of 3 seconds, being
value 3 the last action time of the sequence.

It is important that ALL lines contains the same number of values (in
the example all rows contains exactly 5 values). The number of values
contained by each row, MUST be the number of kpXX output arguments
(notice that, even if kp1, kp2 etc. are placed at the right of the
opcode, they are output arguments, not input arguments).

ktimpnt argument provide the real temporization of the sequence.
Actually the passage of time through sequence is specified by ktimpnt
itself, which represents the time in seconds. ktimpnt must always be
positive, but can move forwards or backwards in time, be stationary or
discontinuous, as a pointer into the sequence file, in the same way of
pvoc or lpread. When ktimpnt crosses the action time of a note, a
trigger signal is sent to ktrig output argument, and kp1, kp2,...kpN
arguments are updated with the values of that note. This information can
then be used with schedkwhen to actually activate note events. Notice
that kp1,...kpn data can be further processed (for example delayed with
delayk, transposed, etc.) before feeding schedkwhen.

ktimpnt can be controlled by a linear signal, for example:

ktimpnt line     0, p3, 3  ; original sequence duration was 3 secs
ktrig   timedseq ktimpnt, 1, kp1, kp2, kp3, kp4, kp5
        schedkwhen   ktrig, 105, 2, 0, kp3, kp4, kp5

in this case the complete sequence (with original duration of 3 seconds)
will be played in p3 seconds.

You can loop a sequence by controlling it with a phasor:

kphs    phasor   1/3
ktimpnt =        kphs * 3
ktrig   timedseq ktimpnt ,1 ,kp1, kp2, kp3, kp4, kp5
        schedkwhen   ktrig, 105, 2, 0, kp3, kp4, kp5

Obviously you can play only a fragment of the sequence, read it
backward, and non-linearly access sequence data in the same way of pvoc
and lpread opcodes.

With timedseq opcode you can do almost all things of a normal score,
except you have the following limitations:

 1. You can't have two notes exactly starting with the same action time;
    actually at least a k-cycle should separate timing of two notes
    (otherwise the schedkwhen mechanism eats one of them).

 2. All notes of the sequence must have the same number of p-fields
    (even if they activate different instruments).

You can remedy this limitation by filling with dummy values notes that
belongs to instruments with less p-fields than other ones.


===========================================================================
timeinstk                                                         *timeinstk*

  Description

Read absolute time, in k-rate cycles, since the start of an instance of
an instrument. Called at both i-time as well as k-time.

  Syntax

kres timeinstk

  Performance

timeinstk is for time in k-rate cycles. So with:

  sr    = 44100
  kr    = 6300
  ksmps = 7

then after half a second, the timeinstk opcode would report 3150. It
will always report an integer.

timeinstk produces a k-rate variable for output. There are no input
parameters.

timeinstk is similar to timek except it returns the time since the start
of this instance of the instrument.


===========================================================================
timeinsts                                                         *timeinsts*

  Description

Read absolute time, in seconds, since the start of an instance of an
instrument.

  Syntax

kres timeinsts

  Performance

Time in seconds is available with timeinsts. This would return 0.5 after
half a second.

timeinsts produces a k-rate variable for output. There are no input
parameters.

timeinsts is similar to times except it returns the time since the start
of this instance of the instrument.


===========================================================================
timek                                                                 *timek*

  Description

Read absolute time, in k-rate cycles, since the start of the performance.

  Syntax

ires timek

kres timek

  Performance

timek is for time in k-rate cycles. So with:

  sr    = 44100
  kr    = 6300
  ksmps = 7

then after half a second, the timek opcode would report 3150. It will
always report an integer.

timek can produce a k-rate variable for output. There are no input
parameters.

timek can also operate only at the start of the instance of the
instrument. It produces an i-rate variable (starting with i or gi) as
its output.


===========================================================================
times                                                                 *times*

  Description

Read absolute time, in seconds, since the start of the performance.

  Syntax

ires times

kres times

  Performance

Time in seconds is available with times. This would return 0.5 after
half a second.

times can both produce a k-rate variable for output. There are no input
parameters.

times can also operate at the start of the instance of the instrument.
It produces an i-rate variable (starting with i or gi) as its output.


===========================================================================
timout                                                               *timout*

  Description

Conditional branch during p-time depending on elapsed note time. istrt
and idur specify time in seconds. The branch to label will become
effective at time istrt, and will remain so for just idur seconds. Note
that timout can be reinitialized for multiple activation within a single
note (see example under reinit).

  Syntax

timout istrt, idur, label

where label is in the same instrument block and is not an expression.


===========================================================================
tival                                                                 *tival*

  Syntax

ir tival

  Description

Puts the value of the instrument's internal “tie-in” flag into the named
i-rate variable.

  Initialization

Puts the value of the instrument's internal “tie-in” flag into the named
i-rate variable. Assigns 1 if this note has been “tied” onto a
previously held note (see i statement); assigns 0 if no tie actually
took place. (See also tigoto.)


===========================================================================
tlineto                                                             *tlineto*

  Description

Generate glissandos starting from a control signal with a trigger.

  Syntax

kres tlineto ksig, ktime, ktrig

  Performance

kres -- Output signal.

ksig -- Input signal.

ktime -- Time length of glissando in seconds.

ktrig -- Trigger signal.

tlineto is similar to lineto but can be applied to any kind of signal
(not only stepped signals) without producing discontinuities. Last value
of each segment is sampled and held from input signal each time ktrig
value is set to a nonzero value. Normally ktrig signal consists of a
sequence of zeroes (see trigger opcode).

The effect of glissando is quite different from port. Since in these
cases, the lines are straight. Also the context of usage is different.


===========================================================================
tone                                                                   *tone*

  Description

A first-order recursive low-pass filter with variable frequency response.

tone is a 1 term IIR filter. Its formula is:

y_n = c1 * x_n + c2 * y_n-1

where

  * b = 2 - cos(2 π hp/sr);

  * c2 = b - sqrt(b^2 - 1.0)

  * c1 = 1 - c2

  Syntax

ares tone asig, khp [, iskip]

  Initialization

iskip (optional, default=0) -- initial disposition of internal data
space. Since filtering incorporates a feedback loop of previous output,
the initial status of the storage space used is significant. A zero
value will clear the space; a non-zero value will allow previous
information to remain. The default value is 0.

  Performance

ares -- the output audio signal.

asig -- the input audio signal.

khp -- the response curve's half-power point, in Hertz. Half power is
defined as peak power / root 2.

tone implements a first-order recursive low-pass filter in which the
variable khp (in Hz) determines the response curve's half-power point.
Half power is defined as peak power / root 2.


===========================================================================
tonek                                                                 *tonek*

  Description

A first-order recursive low-pass filter with variable frequency response.

  Syntax

kres tonek ksig, khp [, iskip]

  Initialization

iskip (optional, default=0) -- initial disposition of internal data
space. Since filtering incorporates a feedback loop of previous output,
the initial status of the storage space used is significant. A zero
value will clear the space; a non-zero value will allow previous
information to remain. The default value is 0.

  Performance

kres -- the output signal at control-rate.

ksig -- the input signal at control-rate.

khp -- the response curve's half-power point, in Hertz. Half power is
defined as peak power / root 2.

tonek is like tone except its output is at control-rate rather than
audio rate.


===========================================================================
tonex                                                                 *tonex*

  Description

tonex is equivalent to a filter consisting of more layers of tone with
the same arguments, serially connected. Using a stack of a larger number
of filters allows a sharper cutoff. They are faster than using a larger
number instances in a Csound orchestra of the old opcodes, because only
one initialization and k- cycle are needed at time and the audio loop
falls entirely inside the cache memory of processor.

  Syntax

ares tonex  asig, khp [, inumlayer] [, iskip]

ares tonex  asig, ahp [, inumlayer] [, iskip]

  Initialization

inumlayer (optional) -- number of elements in the filter stack. Default
value is 4.

iskip (optional, default=0) -- initial disposition of internal data
space. Since filtering incorporates a feedback loop of previous output,
the initial status of the storage space used is significant. A zero
value will clear the space; a non-zero value will allow previous
information to remain. The default value is 0.

  Performance

asig -- input signal

khp/ahp -- the response curve's half-power point. Half power is defined
as peak power / root 2.


===========================================================================
trandom                                                             *trandom*

  Description

Generates a controlled pseudo-random number series between min and max
values at k-rate whenever the trigger parameter is different to 0.

  Syntax

kout trandom ktrig, kmin, kmax

  Performance

ktrig -- trigger (opcode produces a new random number whenever this
value is not 0.

kmin -- minimum range limit

kmax -- maximum range limit

trandom is almost identical to random opcode, except trandom updates its
output with a new random value only when the ktrig argument is triggered
(i.e. whenever it is not zero).


===========================================================================
tradsyn                                                             *tradsyn*

  Description

The tradsyn opcode takes an input containg a TRACKS pv streaming signal
(as generated, for instance by partials),as described in Lazzarini et
al, "Time-stretching using the Instantaneous Frequency Distribution and
Partial Tracking", Proc.of ICMC05, Barcelona. It resynthesises the
signal using linear amplitude and frequency interpolation to drive a
bank of interpolating oscillators with amplitude and pitch scaling
controls.

  Syntax

asig tradsyn fin, kscal, kpitch, kmaxtracks, ifn

  Performance

asig -- output audio rate signal

fin -- input pv stream in TRACKS format

kscal -- amplitude scaling

kpitch -- pitch scaling

kmaxtracks -- max number of tracks in resynthesis. Limiting this will
cause a non-linear filtering effect, by discarding newer and
higher-frequency tracks (tracks are ordered by start time and ascending
frequency, respectively)

ifn -- function table containing one cycle of a sinusoid (sine or cosine).


===========================================================================
transeg                                                             *transeg*

  Description

Constructs a user-definable envelope.

  Syntax

ares transeg ia, idur, itype, ib [, idur2] [, itype] [, ic] ...

kres transeg ia, idur, itype, ib [, idur2] [, itype] [, ic] ...

  Initialization

ia -- starting value.

ib, ic, etc. -- value after idur seconds.

idur -- duration in seconds of first segment. A zero or negative value
will cause all initialization to be skipped.

idur2,... idurx etc. -- duration in seconds of segment

itype, itype2, etc. -- if 0, a straight line is produced. If non-zero,
then transeg creates the following curve, for n steps:

ibeg + (ivalue - ibeg) * (1 - exp( i*itype/(n-1) )) / (1 - exp(itype))

  Performance

If itype > 0, there is a slowly rising (concave) or slowly decaying
(convex) curve, while if itype < 0, the curve is fast rising (convex) or
fast decaying (concave). See also GEN16.


===========================================================================
transegb                                                           *transegb*

  Description

Constructs a user-definable envelope in absolute time.

  Syntax

ares transegb ia, itim, itype, ib [, itim2] [, itype] [, ic] ...

kres transegb ia, itim, itype, ib [, itim2] [, itype] [, ic] ...

  Initialization

ia -- starting value.

ib, ic, etc. -- value after itim seconds.

itim -- time in seconds of end of first segment.

itim2,... itimx etc. -- time in seconds at the end of the segment.

itype, itype2, etc. -- if 0, a straight line is produced. If non-zero,
then transegb creates the following curve, for n steps:

ibeg + (ivalue - ibeg) * (1 - exp( i*itype/(n-1) )) / (1 - exp(itype))

  Performance

If itype > 0, there is a slowly rising (concave) or slowly decaying
(convex) curve, while if itype < 0, the curve is fast rising (convex) or
fast decaying (concave). See also GEN16.


===========================================================================
transegr                                                           *transegr*

  Description

Constructs a user-definable envelope. It is the same as transeg, with an
extended release segment.

  Syntax

ares transegr ia, idur, itype, ib [, idur2] [, itype] [, ic] ...

kres transegr ia, idur, itype, ib [, idur2] [, itype] [, ic] ...

  Initialization

ia -- starting value.

ib, ic, etc. -- value after idur seconds.

idur -- duration in seconds of first segment. A zero or negative value
will cause all initialization to be skipped.

idur2,... idurx etc. -- duration in seconds of segment

itype, itype2, etc. -- if 0, a straight line is produced. If non-zero,
then transegr creates the following curve, for n steps:

ibeg + (ivalue - ibeg) * (1 - exp( i*itype/(n-1) )) / (1 - exp(itype))

  Performance

If itype > 0, there is a slowly rising (concave) or slowly decaying
(convex) curve, while if itype < 0, the curve is fast rising (convex) or
fast decaying (concave). See also GEN16.

This opcode is the same as of transeg with an additional release segment
triggered by a MIDI noteoff event, a negative p1 note event in the score
or a turnoff2 opcode.


===========================================================================
trcross                                                             *trcross*

  Description

The trcross opcode takes two inputs containg TRACKS pv streaming signals
(as generated, for instance by partials) and cross-synthesises them into
a single TRACKS stream. Two different modes of operation are used: mode
0, cross-synthesis by multiplication of the amplitudes of the two inputs
and mode 1, cross-synthesis by the substititution of the amplitudes of
input 1 by the input 2. Frequencies and phases of input 1 are preserved
in the output. The cross-synthesis is done by matching tracks between
the two inputs using a 'search interval'. The matching algorithm will
look for tracks in the second input that are within the search interval
around each track in the first input. This interval can be changed at
the control rate. Wider search intervals will find more matches.

  Syntax

fsig trcross fin1, fin2, ksearch, kdepth [, kmode] 

  Performance

fsig -- output pv stream in TRACKS format

fin1 -- first input pv stream in TRACKS format.

fin2 -- second input pv stream in TRACKS format

ksearch -- search interval ratio, defining a 'search area' around each
track of 1st input for matching purposes.

kdepth -- depth of effect (0-1).

kmode -- mode of cross-synthesis. 0, multiplication of amplitudes
(filtering), 1, subsitution of amplitudes of input 1 by input 2 (akin to
vocoding). Defaults to 0.


===========================================================================
trfilter                                                           *trfilter*

  Description

The trfilter opcode takes an input containg a TRACKS pv streaming signal
(as generated, for instance by partials) and filters it using an
amplitude response curve stored in a function table. The function table
can have any size (no restriction to powers-of-two). The table lookup is
done by linear-interpolation. It is possible to create time-varying
filter curves by updating the amlitude response table with a
table-writing opcode.

  Syntax

fsig trfilter fin, kamnt, ifn

  Performance

fsig -- output pv stream in TRACKS format

fin -- input pv stream in TRACKS format

kamnt -- amount of filtering (0-1)

ifn -- function table number. This will contain an amplitude response
curve, from 0 Hz to the Nyquist (table indexes 0 to N). Any size is
allowed. Larger tables will provide a smoother amplitude response curve.
Table reading uses linear interpolation.


===========================================================================
trhighest                                                         *trhighest*

  Description

The trhighest opcode takes an input containg TRACKS pv streaming signals
(as generated, for instance by partials) and outputs only the highest
track. In addition it outputs two k-rate signals, corresponding to the
frequency and amplitude of the highest track signal.

  Syntax

fsig, kfr, kamp trhighest fin1, kscal

  Performance

fsig -- output pv stream in TRACKS format

kfr -- frequency (in Hz) of the highest-frequency track

kamp -- amplitude of the highest-frequency track

fin -- input pv stream in TRACKS format.

kscal -- amplitude scaling of output.


===========================================================================
trigger                                                             *trigger*

  Description

Informs when a krate signal crosses a threshold.

  Syntax

kout trigger ksig, kthreshold, kmode

  Performance

ksig -- input signal

kthreshold -- trigger threshold

kmode -- can be 0 , 1 or 2

Normally trigger outputs zeroes: only each time ksig crosses kthreshold
trigger outputs a 1. There are three modes of using ktrig:

  * kmode = 0 - (down-up) ktrig outputs a 1 when current value of ksig
    is higher than kthreshold, while old value of ksig was equal to or
    lower than kthreshold.

  * kmode = 1 - (up-down) ktrig outputs a 1 when current value of ksig
    is lower than kthreshold while old value of ksig was equal or higher
    than kthreshold.

  * kmode = 2 - (both) ktrig outputs a 1 in both the two previous cases.


===========================================================================
trigseq                                                             *trigseq*

  Description

Accepts a trigger signal as input and outputs a group of values.

  Syntax

trigseq ktrig_in, kstart, kloop, kinitndx, kfn_values, kout1 [, kout2] [...]

  Performance

ktrig_in -- input trigger signal

kstart -- start index of looped section

kloop -- end index of looped section

kinitndx -- initial index

  Note

Although kinitndx is listed as k-rate, it is in fact accessed only at
init-time. So if you are using a k-rate argument, it must be assigned
with init.

kfn_values -- number of a table containing a sequence of groups of values

kout1 -- output values

kout2, ... (optional) -- more output values

This opcode handles timed-sequences of groups of values stored into a
table.

trigseq accepts a trigger signal (ktrig_in) as input and outputs group
of values (contained in the kfn_values table) each time ktrig_in assumes
a non-zero value. Each time a group of values is triggered, table
pointer is advanced of a number of positions corresponding to the number
of group-elements, in order to point to the next group of values. The
number of elements of groups is determined by the number of koutX
arguments.

It is possible to start the sequence from a value different than the
first, by assigning to kinitndx an index different than zero (which
corresponds to the first value of the table). Normally the sequence is
looped, and the start and end of loop can be adjusted by modifying
kstart and kloop arguments. User must be sure that values of these
arguments (as well as kinitndx) correspond to valid table numbers,
otherwise Csound will crash because no range-checking is implemented.

It is possible to disable loop (one-shot mode) by assigning the same
value both to kstart and kloop arguments. In this case, the last read
element will be the one corresponding to the value of such arguments.
Table can be read backward by assigning a negative kloop value.

trigseq is designed to be used together with seqtime or trigger opcodes.


===========================================================================
trirand                                                             *trirand*

  Description

Triangular distribution random number generator. This is an x-class
noise generator.

  Syntax

ares trirand krange

ires trirand krange

kres trirand krange

  Performance

krange -- the range of the random numbers (-krange to +krange).

For more detailed explanation of these distributions, see:

 1. C. Dodge - T.A. Jerse 1985. Computer music. Schirmer books. pp.265 - 286

 2. D. Lorrain. A panoply of stochastic cannons. In C. Roads, ed. 1989.
    Music machine . Cambridge, Massachusetts: MIT press, pp. 351 - 379.


===========================================================================
trlowest                                                           *trlowest*

  Description

The trlowest opcode takes an input containg TRACKS pv streaming signals
(as generated, for instance by partials) and outputs only the lowest
track. In addition it outputs two k-rate signals, corresponding to the
frequency and amplitude of the lowest track signal.

  Syntax

fsig, kfr, kamp trlowest fin1, kscal

  Performance

fsig -- output pv stream in TRACKS format

kfr -- frequency (in Hz) of the lowest-frequency track

kamp -- amplitude of the lowest-frequency track

fin -- input pv stream in TRACKS format.

kscal -- amplitude scaling of output.


===========================================================================
trmix                                                                 *trmix*

  Description

The trmix opcode takes two inputs containg TRACKS pv streaming signals
(as generated, for instance by partials) and mixes them into a single
TRACKS stream. Tracks will be mixed up to the available space (defined
by the original number of FFT bins in the analysed signals). If the sum
of the input tracks exceeds this space, the higher-ordered tracks in the
second input will be pruned.

  Syntax

fsig trmix fin1, fin2 

  Performance

fsig -- output pv stream in TRACKS format

fin1 -- first input pv stream in TRACKS format.

fin2 -- second input pv stream in TRACKS format


===========================================================================
trscale                                                             *trscale*

  Description

The trscale opcode takes an input containg a TRACKS pv streaming signal
(as generated, for instance by partials) and scales all frequencies by a
k-rate amount. It can also, optionally, scale the gain of the signal by
a k-rate amount (default 1). The result is pitch shifting of the input
tracks.

  Syntax

fsig trscale fin, kpitch[, kgain]

  Performance

fsig -- output pv stream in TRACKS format

fin -- input pv stream in TRACKS format

kpitch -- frequency scaling

kgain -- amplitude scaling (default 1)


===========================================================================
trshift                                                             *trshift*

  Description

The trshift opcode takes an input containg a TRACKS pv streaming signal
(as generated, for instance by partials) and shifts all frequencies by a
k-rate frequency. It can also, optionally, scale the gain of the signal
by a k-rate amount (default 1). The result is frequency shifting of the
input tracks.

  Syntax

fsig trshift fin, kpshift[, kgain]

  Performance

fsig -- output pv stream in TRACKS format

fin -- input pv stream in TRACKS format

kshift -- frequency shift in Hz

kgain -- amplitude scaling (default 1)


===========================================================================
trsplit                                                             *trsplit*

  Description

The trsplit opcode takes an input containg a TRACKS pv streaming signal
(as generated, for instance by partials) and splits it into two signals
according to a k-rate frequency 'split point'. The first output will
contain all tracks up from 0Hz to the split frequency and the second
will contain the tracks from the split frequency up to the Nyquist. It
can also, optionally, scale the gain of the output signals by a k-rate
amount (default 1). The result is two output signals containing only
part of the original spectrum.

  Syntax

fsiglow, fsighi trsplit fin, ksplit[, kgainlow, kgainhigh]

  Performance

fsiglow -- output pv stream in TRACKS format containing the tracks below
the split point.

fsighi -- output pv stream in TRACKS format containing the tracks above
and including the split point.

fin -- input pv stream in TRACKS format

ksplit -- frequency split point in Hz

kgainlow, kgainhig -- amplitude scaling of each one of the outputs
(default 1).


===========================================================================
turnoff                                                             *turnoff*

  Description

Enables an instrument to turn itself off or to turn an instance of
another instrument off.

  Syntax

turnoff

turnoff inst

turnoff knst

  Initialization

inst -- when used with an i-time parameter, this is the instance handle
of an instrument to be turned off (obtained from the nstance opcode).

turnoff -- with no parameters this p-time statement enables an
instrument to turn itself off. Whether of finite duration or “held”, the
note currently being performed by this instrument is immediately removed
from the active note list. No other notes are affected.

kinst -- when used with an k-time parameter, this is the instance handle
of an instrument to be turned off (obtained from the nstance opcode).


===========================================================================
turnoff2                                                           *turnoff2*

  Description

Turn off instance(s) of other instruments at performance time.

  Syntax

turnoff2 kinsno, kmode, krelease

  Performance

kinsno -- instrument to be turned off (can be fractional) if zero or
negative, no instrument is turned off

kmode -- sum of the following values:

  * 0, 1, or 2: turn off all instances (0), oldest only (1), or newest
    only (2)

  * 4: only turn off notes with exactly matching (fractional) instrument
    number, rather than ignoring fractional part

  * 8: only turn off notes with indefinite duration (p3 < 0 or MIDI)

krelease -- if non-zero, the turned off instances are allowed to
release, otherwise are deactivated immediately (possibly resulting in
clicks)

  Note

As a rule of thumb, you should turn off instruments with a higher
instrument number than the one where turnoff is called, as doing
otherwise might cause initialization issues.


===========================================================================
turnon                                                               *turnon*

  Description

Activate an instrument for an indefinite time.

  Syntax

turnon insnum [, itime]

  Initialization

insnum -- instrument number to be activated

itime (optional, default=0) -- delay, in seconds, after which instrument
insnum will be activated. Default is 0.

  Performance

turnon activates instrument insnum after a delay of itime seconds, or
immediately if itime is not specified. Instrument is active until
explicitly turned off. (See turnoff.)


===========================================================================
unirand                                                             *unirand*

  Description

Uniform distribution random number generator (positive values only).
This is an x-class noise generator.

  Syntax

ares unirand krange

ires unirand krange

kres unirand krange

  Performance

krange -- the range of the random numbers (0 - krange).

For more detailed explanation of these distributions, see:

 1. C. Dodge - T.A. Jerse 1985. Computer music. Schirmer books. pp.265 - 286

 2. D. Lorrain. A panoply of stochastic cannons. In C. Roads, ed. 1989.
    Music machine . Cambridge, Massachusetts: MIT press, pp. 351 - 379.


===========================================================================
until                                                                 *until*

  Description

A syntactic looping construction.

  Syntax

until  condition do
    ... od

  Performance

The statements between the do and od form the body of a loop which is
obeyed until the conditional becomes true.


===========================================================================
unwrap                                                               *unwrap*

  Description

Applies a unwrapping operation to a vector of phases stored in an array.
The output is an array with phases in the range of [-pi,pi).

  Syntax

kout[] unwrap kin[] 

  Performance

kout[] -- output array containing the unwrapped phases. It will be
created if it does not exist.

kin[] -- input array containing the input vector.


===========================================================================
upsamp                                                               *upsamp*

  Description

Modify a signal by up-sampling.

  Syntax

ares upsamp ksig

  Performance

upsamp converts a control signal to an audio signal. It does it by
simple repetition of the kval. upsamp is a slightly more efficient form
of the assignment, asig = ksig.


===========================================================================
urandom                                                             *urandom*

  Description

Truly random opcodes with controllable range. These units are for
Unix-like systems only and use /dev/urandom to construct Csound random
values

  Syntax

ax urandom [imin, imax]

ix urandom [imin, imax]

kx urandom [imin, imax]

  Initialization

ix -- i-rate output value.

imin -- minimum value of range; defaults to -1.

imax -- maximum value of range; defaults to +1.

  Notes

The algorithm produces 2^64 different possible values which are scaled
to fit the range requested. The randomness comes form the usual
Linux/OSX /dev/urandom method, and there is no guarantee that it will be
truly random, but there is a good chance. It does not show any cycles.

  Performance

ax -- a-rate output value.

kx -- k-rate output value.


===========================================================================
urd                                                                     *urd*

  Description

A discrete user-defined-distribution random generator that can be used
as a function.

  Syntax

aout = urd(ktableNum)

iout = urd(itableNum)

kout = urd(ktableNum)

  Initialization

itableNum -- number of table containing the random-distribution
function. Such table is generated by the user. See GEN40, GEN41, and
GEN42. The table length does not need to be a power of 2

  Performance

ktableNum -- number of table containing the random-distribution
function. Such table is generated by the user. See GEN40, GEN41, and
GEN42. The table length does not need to be a power of 2

urd is the same opcode as duserrnd, but can be used in function fashion.

For a tutorial about random distribution histograms and functions see:

  * D. Lorrain. "A panoply of stochastic cannons". In C. Roads, ed.
    1989. Music machine. Cambridge, Massachusetts: MIT press, pp. 351 -
    379.


===========================================================================
vactrol                                                             *vactrol*

  Description

Envelope follower unit generator emmulating a Perkin Elmer Vactrole
VTL5C3/2.

  Syntax

ares vactrol asig [iup, idown]

  Initialisation

iup -- The rise time of the filter, which defaults to 20,

idown -- The fall time of the filter, which defaults to 3000,

  Performance

asig -- The signal from which to extract the envelope.


===========================================================================
vadd                                                                   *vadd*

  Description

Adds a scalar value to a vector in a table.

  Syntax

vadd  ifn, kval, kelements [, kdstoffset] [, kverbose]

  Initialization

ifn - number of the table hosting the vectorial signal to be processed

  Performance

kval - scalar value to be added

kelements - number of elements of the vector

kdstoffset - index offset for the destination table (Optional, default=0)

kverbose - Selects whether or not warnings are printed (Optional,
default=0)

vadd adds the value of kval to each element of the vector contained in
the table ifn, starting from table index kdstoffset. This enables you to
process a specific section of a table by specifying the offset and the
number of elements to be processed. Offset is counted starting from 0,
so if no offset is specified (or set to 0), the table will be modified
from the beginning.

Note that this opcode runs at k-rate so the value of kval is added every
control period. Use with care or you will end up with very large numbers
(or use vadd_i).

These opcodes (vadd, vmult, vpow and vexp) perform numeric operations
between a vectorial control signal (hosted by the table ifn), and a
scalar signal (kval). Result is a new vector that overrides old values
of ifn. All these opcodes work at k-rate.

Negative values for kdstoffset are valid. Elements from the vector that
are outside the table, will be discarded, and they will not wrap around
the table.

If the optional kverbose argument is different to 0, the opcode will
print warning messages every k-pass if table lengths are exceeded.

In all these opcodes, the resulting vectors are stored in ifn,
overriding the intial vectors. If you want to keep initial vector, use
vcopy or vcopy_i to copy it in another table. All these operators are
designed to be used together with other opcodes that operate with
vectorial signals such as vcella, adsynt, adsynt2, etc. They can also be
useful in conjunction with the spectral opcodes pvsftw and pvsftr.

  Note

Please note that the elements argument has changed in version 5.03 from
i-rate to k-rate. This will change the opcode's behavior in the unusual
cases where the i-rate variable ielements is changed inside the
instrument, for example in:

instr 1
ielements  =        10
           vadd     1, 1, ielements
ielements  =        20
           vadd     2, 1, ielements
           turnoff
    endin


===========================================================================
vadd_i                                                               *vadd_i*

  Description

Adds a scalar value to a vector in a table.

  Syntax

vadd_i  ifn, ival, ielements [, idstoffset]

  Initialization

ifn - number of the table hosting the vectorial signal to be processed

ielements - number of elements of the vector

ival - scalar value to be added

idstoffset - index offset for the destination table

  Performance

vadd_i adds the value of ival to each element of the vector contained in
the table ifn, starting from table index idstoffset. This enables you to
process a specific section of a table by specifying the offset and the
number of elements to be processed. Offset is counted starting from 0,
so if no offset is specified (or set to 0), the table will be modified
from the beginning.

This opcode runs only on initialization, there is a k-rate version of
this opcode called vadd.

Negative values for idstoffset are valid. Elements from the vector that
are outside the table, will be discarded, and they will not wrap around
the table.

In all these opcodes, the resulting vectors are stored in ifn,
overriding the intial vectors. If you want to keep initial vector, use
vcopy or vcopy_i to copy it in another table. All these operators are
designed to be used together with other opcodes that operate with
vectorial signals such as vcella, adsynt, adsynt2, etc. They can also be
useful in conjunction with the spectral opcodes pvsftw and pvsftr.


===========================================================================
vaddv                                                                 *vaddv*

  Description

Performs addition between two vectorial control signals.

  Syntax

vaddv  ifn1, ifn2, kelements [, kdstoffset] [, ksrcoffset] [,kverbose]

  Initialization

ifn1 - number of the table hosting the first vector to be processed

ifn2 - number of the table hosting the second vector to be processed

  Performance

kelements - number of elements of the two vectors

kdstoffset - index offset for the destination (ifn1) table (Default=0)

ksrcoffset - index offset for the source (ifn2) table (Default=0)

kverbose - Selects whether or not warnings are printed (Default=0)

vaddv adds two vectorial control signals, that is, each element of the
first vector is processed (only) with the corresponding element of the
other vector. Each vectorial signal is hosted by a table (ifn1 and
ifn2). The number of elements contained in both vectors must be the same.

The result is a new vectorial control signal that overrides old values
of ifn1. If you want to keep the old ifn1 vector, use vcopy_iopcode to
copy it in another table. You can use kdstoffset and ksrcoffset to
specify vectors in any location of the tables.

Negative values for kdstoffset and ksrcoffset are acceptable. If
kdstoffset is negative, the out of range section of the vector will be
discarded. If ksrcoffset is negative, the out of range elements will be
assumed to be 0 (i.e. the destination elements will not be changed). If
elements for the destination vector are beyond the size of the table
(including guard point), these elements are discarded (i.e. elements do
not wrap around the tables). If elements for the source vector are
beyond the table length, these elements are taken as 0 (i.e. the
destination vector will not be changed for these elements).

  Warning

Using the same table as source and destination table in versions earlier
than 5.04, might produce unexpected behavior, so use with care.

This opcode works at k-rate (this means that every k-pass the vectors
are added). There's an i-rate version of this opcode called vaddv_i.

  Note

Please note that the elements argument has changed in version 5.03 from
i-rate to k-rate. This will change the opcode's behavior in the unusual
cases where the i-rate variable ielements is changed inside the
instrument, for example in:

instr 1
ielements  =        10
           vadd     1, 1, ielements
ielements  =        20
           vadd     2, 1, ielements
           turnoff
    endin

All these operators (vaddv,vsubv,vmultv,vdivv,vpowv,vexpv, vcopy and
vmap) are designed to be used together with other opcodes that operate
with vectorial signals such as vcella, adsynt, adsynt2 etc.


===========================================================================
vaddv_i                                                             *vaddv_i*

  Description

Performs addition between two vectorial control signals at init time.

  Syntax

vaddv_i  ifn1, ifn2, ielements [, idstoffset] [, isrcoffset]

  Initialization

ifn1 - number of the table hosting the first vector to be processed

ifn2 - number of the table hosting the second vector to be processed

ielements - number of elements of the two vectors

idstoffset - index offset for the destination (ifn1) table (Default=0)

isrcoffset - index offset for the source (ifn2) table (Default=0)

  Performance

vaddv_i adds two vectorial control signals, that is, each element of the
first vector is processed (only) with the corresponding element of the
other vector. Each vectorial signal is hosted by a table (ifn1 and
ifn2). The number of elements contained in both vectors must be the same.

The result is a new vectorial control signal that overrides old values
of ifn1. If you want to keep the old ifn1 vector, use vcopy_i opcode to
copy it in another table. You can use idstoffset and isrcoffset to
specify vectors in any location of the tables.

Negative values for idstoffset and isrcoffset are acceptable. If
idstoffset is negative, the out of range section of the vector will be
discarded. If isrcoffset is negative, the out of range elements will be
assumed to be 0 (i.e. the destination elements will not be changed). If
elements for the destination vector are beyond the size of the table
(including guard point), these elements are discarded (i.e. elements do
not wrap around the tables). If elements for the source vector are
beyond the table length, these elements are taken as 0 (i.e. the
destination vector will not be changed for these elements).

  Warning

Using the same table as source and destination table in versions earlier
than 5.04, might produce unexpected behavior, so use with care.

This opcode works at init time. There's an k-rate version of this opcode
called vaddv.

All these operators (vaddv_i,vsubv_i,vmultv_i,vdivv_i,vpowv_i,vexpv_i,
vcopy and vmap) are designed to be used together with other opcodes that
operate with vectorial signals such as vcella, adsynt, adsynt2 etc.


===========================================================================
vaget                                                                 *vaget*

  Description

Access values of the current buffer of an a-rate variable by indexing.
Useful for doing sample-by-sample manipulation at k-rate without using
setksmps 1.

  Note

Because this opcode does not do any bounds checking, the user must be
careful not to try to read values past ksmps (the size of a buffer for
an a-rate variable) by using index values greater than ksmps.

  Note

In Csound6 this opcode does do bounds checking.

  Syntax

kval vaget kndx, avar

  Performance

kval - value read from avar

kndx - index of the sample to read from the current buffer of the given
avar variable

avar - a-rate variable to read from


===========================================================================
valpass                                                             *valpass*

  Description

Variably reverberates an input signal with a flat frequency response.

  Syntax

ares valpass asig, krvt, xlpt, imaxlpt [, iskip] [, insmps]

  Initialization

imaxlpt -- maximum loop time for klpt

iskip (optional, default=0) -- initial disposition of delay-loop data
space (cf. reson). The default value is 0.

insmps (optional, default=0) -- delay amount, as a number of samples.

  Performance

krvt -- the reverberation time (defined as the time in seconds for a
signal to decay to 1/1000, or 60dB down from its original amplitude).

xlpt -- variable loop time in seconds, same as ilpt in comb. Loop time
can be as large as imaxlpt.

This filter reiterates input with an echo density determined by loop
time xlpt. The attenuation rate is independent and is determined by
krvt, the reverberation time (defined as the time in seconds for a
signal to decay to 1/1000, or 60dB down from its original amplitude).
Its output will begin to appear immediately.


===========================================================================
vaset                                                                 *vaset*

  Description

Write values into the current buffer of an a-rate variable at the given
index. Useful for doing sample-by-sample manipulation at k-rate without
using setksmps 1.

  Note

Because this opcode does not do any bounds checking, the user must be
careful not to try to write values past ksmps (the size of a buffer for
an a-rate variable) by using index values greater than ksmps.

  Note

In Csound6 this opcode does do bounds checking.

  Syntax

vaset kval, kndx, avar

  Performance

kval - value to write into avar

kndx - index of the sample to write to the current buffer of the given
avar variable

avar - a-rate variable to write to


===========================================================================
vbap                                                                   *vbap*

  Description

Distributes an audio signal amongmany channels, up to 64 in the first
form, arbitrary in the second.

  Syntax

ar1[, ar2...] vbap asig, kazim [,
    kelev] [, kspread] [, ilayout]

array[] vbap asig, kazim [,
    kelev] [, kspread] [, ilayout]

  Initialization

ilayout -- index of the speaker layout in the range 0-99, corresponding
to a call to vbaplsinit.

  Performance

asig -- audio signal to be panned

kazim -- azimuth angle of the virtual source

kelev (optional) -- elevation angle of the virtual source

kspread (optional) -- spreading of the virtual source (range 0 - 100).
If value is zero, conventional amplitude panning is used. When kspread
is increased, the number of loudspeakers used in panning increases. If
value is 100, the sound is applied to all loudspeakers.

vbap takes an input signal, asig and distributes it among the outputs,
according to the controls kazim and kelev, and the configured
loudspeaker placement. If idim = 2, kelev is set to zero. The
distribution is performed using Vector Base Amplitude Panning (VBAP -
See reference). VBAP distributes the signal using loudspeaker data
configured with vbaplsinit. The signal is applied to, at most, two
loudspeakers in 2-D loudspeaker configurations, and three loudspeakers
in 3-D loudspeaker configurations. If the virtual source is panned
outside the region spanned by loudspeakers, the nearest loudspeakers are
used in panning.

  Warning

Please note that all vbap panning opcodes require the vbap system to be
initialized using vbaplsinit.


===========================================================================
vbapmove                                                           *vbapmove*

  Description

Distributes an audio signal among upto 64 channels with moving virtual
sources.

  Syntax

ar1[, ar2...] vbapmove asig, idur, ispread, ifldnum, ifld1 \
      [, ifld2] [...]

aarray[] vbapmove asig, idur, ispread, ifldnum, ifld1 \
      [, ifld2] [...]

  Initialization

idur -- the duration over which the movement takes place.

ispread -- spreading of the virtual source (range 0 - 100). If value is
zero, conventional amplitude panning is used. When ispread is increased,
the number of loudspeakers used in panning increases. If value is 100,
the sound is applied to all loudspeakers.

ifldnum -- number of fields (absolute value must be 2 or larger). If
ifldnum is positive, the virtual source movement is a polyline specified
by given directions. Each transition is performed in an equal time
interval. If ifldnum is negative, specified angular velocities are
applied to the virtual source during specified relative time intervals
(see below).

ifld1, ifld2, ... -- azimuth angles or angular velocities, and relative
durations of movement phases (see below).

  Performance

asig -- audio signal to be panned

vbapmove allows the use of moving virtual sources. If ifldnum is
positive, the fields represent directions of virtual sources and equal
times, iazi1, [iele1,] iazi2, [iele2,], etc. The position of the virtual
source is interpolated between directions starting from the first
direction and ending at the last. Each interval is interpolated in time
that is fraction total_time / number_of_intervals of the duration of the
sound event.

If ifldnum is negative, the fields represent angular velocities and
equal times. The first field is, however, the starting direction, iazi1,
[iele1,] iazi_vel1, [iele_vel1,] iazi_vel2, [iele_vel2,] .... Each
velocity is applied to the note that is fraction total_time /
number_of_velocities of the duration of the sound event. If the
elevation of the virtual source becomes greater than 90 degrees or less
than 0 degrees, the polarity of angular velocity is changed. Thus the
elevational angular velocity produces a virtual source that moves up and
down between 0 and 90 degrees.

  Warning

Please note that all vbap panning opcodes require the vbap system to be
initialized using vbaplsinit.


===========================================================================
vbapg                                                                 *vbapg*

  Description

Calculates the gains for a sound location for up to 64.

  Syntax

k1[, k2...] vbapg kazim [,kelev] [, kspread] [, ilayout]

karray[] vbapg kazim [,kelev] [, kspread] [, ilayout]

  Initialization

ilayout -- index of the speaker layout in the range 0-99, corresponding
to a call to vbaplsinit. The default value is 0.

  Performance

kazim -- azimuth angle of the virtual source

kelev (optional) -- elevation angle of the virtual source

kspread (optional) -- spreading of the virtual source (range 0 - 100).
If value is zero, conventional amplitude panning is used. When kspread
is increased, the number of loudspeakers used in panning increases. If
value is 100, the sound is applied to all loudspeakers.

vbapg calculates the gains that an input signal would have between
multiple speakers according to the controls kazim and kelev, and the
configured loudspeaker placement ilayout. If idim = 2, kelev is set to
zero. The distribution is performed using Vector Base Amplitude Panning
(VBAP - See reference). VBAP distributes the signal using loudspeaker
data configured with vbaplsinit. The signal is applied to, at most, two
loudspeakers in 2-D loudspeaker configurations, and three loudspeakers
in 3-D loudspeaker configurations. If the virtual source is panned
outside the region spanned by loudspeakers, the nearest loudspeakers are
used in panning.

  Warning

Please note that all vbap panning opcodes require the vbap system to be
initialized using vbaplsinit.


===========================================================================
vbapgmove                                                         *vbapgmove*

  Description

Calculates the gains for a sound location between multiple channels with
moving virtual sources.

  Syntax

kr1[, kr2...] vbapgmove idur, ispread, ifldnum, ifld1 \
      [, ifld2] [...]

karray[] vbapgmove idur, ispread, ifldnum, ifld1 \
      [, ifld2] [...]

  Initialization

idur -- the duration over which the movement takes place.

ispread -- spreading of the virtual source (range 0 - 100). If value is
zero, conventional amplitude panning is used. When ispread is increased,
the number of loudspeakers used in panning increases. If value is 100,
the sound is applied to all loudspeakers.

ifldnum -- number of fields (absolute value must be 2 or larger). If
ifldnum is positive, the virtual source movement is a polyline specified
by given directions. Each transition is performed in an equal time
interval. If ifldnum is negative, specified angular velocities are
applied to the virtual source during specified relative time intervals
(see below).

ifld1, ifld2, ... -- azimuth angles or angular velocities, and relative
durations of movement phases (see below).

  Performance

vbapgmove allows the use of moving virtual sources. If ifldnum is
positive, the fields represent directions of virtual sources and equal
times, iazi1, [iele1,] iazi2, [iele2,], etc. The position of the virtual
source is interpolated between directions starting from the first
direction and ending at the last. Each interval is interpolated in time
that is fraction total_time / number_of_intervals of the duration of the
sound event.

If ifldnum is negative, the fields represent angular velocities and
equal times. The first field is, however, the starting direction, iazi1,
[iele1,] iazi_vel1, [iele_vel1,] iazi_vel2, [iele_vel2,] .... Each
velocity is applied to the note that is fraction total_time /
number_of_velocities of the duration of the sound event. If the
elevation of the virtual source becomes greater than 90 degrees or less
than 0 degrees, the polarity of angular velocity is changed. Thus the
elevational angular velocity produces a virtual source that moves up and
down between 0 and 90 degrees.

  Warning

Please note that all vbap panning opcodes require the vbap system to be
initialized using vbaplsinit.


===========================================================================
vbap16                                                               *vbap16*

  Description

Distributes an audio signal among 16 channels.

  Syntax

ar1, ..., ar16 vbap16 asig, kazim [, kelev] [, kspread]

  Performance

asig -- audio signal to be panned

kazim -- azimuth angle of the virtual source

kelev (optional) -- elevation angle of the virtual source

kspread (optional) -- spreading of the virtual source (range 0 - 100).
If value is zero, conventional amplitude panning is used. When kspread
is increased, the number of loudspeakers used in panning increases. If
value is 100, the sound is applied to all loudspeakers.

vbap16 takes an input signal, asig, and distribute it among 16 outputs,
according to the controls kazim and kelev, and the configured
loudspeaker placement. If idim = 2, kelev is set to zero. The
distribution is performed using Vector Base Amplitude Panning (VBAP -
See reference). VBAP distributes the signal using loudspeaker data
configured with vbaplsinit. The signal is applied to, at most, two
loudspeakers in 2-D loudspeaker configurations, and three loudspeakers
in 3-D loudspeaker configurations. If the virtual source is panned
outside the region spanned by loudspeakers, the nearest loudspeakers are
used in panning.

  Warning

Please note that all vbap panning opcodes require the vbap system to be
initialized using vbaplsinit.


===========================================================================
vbap16move                                                       *vbap16move*

  Description

Distribute an audio signal among 16 channels with moving virtual sources.

  Syntax

ar1, ..., ar16 vbap16move asig, idur, ispread, ifldnum, ifld1 \
      [, ifld2] [...]

  Initialization

idur -- the duration over which the movement takes place.

ispread -- spreading of the virtual source (range 0 - 100). If value is
zero, conventional amplitude panning is used. When ispread is increased,
the number of loudspeakers used in panning increases. If value is 100,
the sound is applied to all loudspeakers.

ifldnum -- number of fields (absolute value must be 2 or larger). If
ifldnum is positive, the virtual source movement is a polyline specified
by given directions. Each transition is performed in an equal time
interval. If ifldnum is negative, specified angular velocities are
applied to the virtual source during specified relative time intervals
(see below).

ifld1, ifld2, ... -- azimuth angles or angular velocities, and relative
durations of movement phases.

  Performance

asig -- audio signal to be panned

vbap16move allows the use of moving virtual sources. If ifldnum is
positive, the fields represent directions of virtual sources and equal
times, iazi1, [iele1,] iazi2, [iele2,], etc. The position of the virtual
source is interpolated between directions starting from the first
direction and ending at the last. Each interval is interpolated in time
that is fraction total_time / number_of_intervals of the duration of the
sound event.

If ifldnum is negative, the fields represent angular velocities and
equal times. The first field is, however, the starting direction, iazi1,
[iele1,] iazi_vel1, [iele_vel1,] iazi_vel2, [iele_vel2,] .... Each
velocity is applied to the note that is fraction total_time /
number_of_velocities of the duration of the sound event. If the
elevation of the virtual source becomes greater than 90 degrees or less
than 0 degrees, the polarity of angular velocity is changed. Thus the
elevational angular velocity produces a virtual source that moves up and
down between 0 and 90 degrees.

  Warning

Please note that all vbap panning opcodes require the vbap system to be
initialized using vbaplsinit.


===========================================================================
vbap4                                                                 *vbap4*

  Description

Distributes an audio signal among 4 channels.

  Syntax

ar1, ar2, ar3, ar4 vbap4 asig, kazim [, kelev] [, kspread]

  Performance

asig -- audio signal to be panned

kazim -- azimuth angle of the virtual source

kelev (optional) -- elevation angle of the virtual source

kspread (optional) -- spreading of the virtual source (range 0 - 100).
If value is zero, conventional amplitude panning is used. When kspread
is increased, the number of loudspeakers used in panning increases. If
value is 100, the sound is applied to all loudspeakers.

vbap4 takes an input signal, asig and distributes it among 4 outputs,
according to the controls kazim and kelev, and the configured
loudspeaker placement. If idim = 2, kelev is set to zero. The
distribution is performed using Vector Base Amplitude Panning (VBAP -
See reference). VBAP distributes the signal using loudspeaker data
configured with vbaplsinit. The signal is applied to, at most, two
loudspeakers in 2-D loudspeaker configurations, and three loudspeakers
in 3-D loudspeaker configurations. If the virtual source is panned
outside the region spanned by loudspeakers, the nearest loudspeakers are
used in panning.

  Warning

Please note that all vbap panning opcodes require the vbap system to be
initialized using vbaplsinit.


===========================================================================
vbap4move                                                         *vbap4move*

  Description

Distributes an audio signal among 4 channels with moving virtual sources.

  Syntax

ar1, ar2, ar3, ar4 vbap4move asig, idur, ispread, ifldnum, ifld1 \
      [, ifld2] [...]

  Initialization

idur -- the duration over which the movement takes place.

ispread -- spreading of the virtual source (range 0 - 100). If value is
zero, conventional amplitude panning is used. When ispread is increased,
the number of loudspeakers used in panning increases. If value is 100,
the sound is applied to all loudspeakers.

ifldnum -- number of fields (absolute value must be 2 or larger). If
ifldnum is positive, the virtual source movement is a polyline specified
by given directions. Each transition is performed in an equal time
interval. If ifldnum is negative, specified angular velocities are
applied to the virtual source during specified relative time intervals
(see below).

ifld1, ifld2, ... -- azimuth angles or angular velocities, and relative
durations of movement phases (see below).

  Performance

asig -- audio signal to be panned

vbap4move allows the use of moving virtual sources. If ifldnum is
positive, the fields represent directions of virtual sources and equal
times, iazi1, [iele1,] iazi2, [iele2,], etc. The position of the virtual
source is interpolated between directions starting from the first
direction and ending at the last. Each interval is interpolated in time
that is fraction total_time / number_of_intervals of the duration of the
sound event.

If ifldnum is negative, the fields represent angular velocities and
equal times. The first field is, however, the starting direction, iazi1,
[iele1,] iazi_vel1, [iele_vel1,] iazi_vel2, [iele_vel2,] .... Each
velocity is applied to the note that is fraction total_time /
number_of_velocities of the duration of the sound event. If the
elevation of the virtual source becomes greater than 90 degrees or less
than 0 degrees, the polarity of angular velocity is changed. Thus the
elevational angular velocity produces a virtual source that moves up and
down between 0 and 90 degrees.

  Warning

Please note that all vbap panning opcodes require the vbap system to be
initialized using vbaplsinit.


===========================================================================
vbap8                                                                 *vbap8*

  Description

Distributes an audio signal among 8 channels.

  Syntax

ar1, ..., ar8 vbap8 asig, kazim [, kelev] [, kspread]

  Performance

asig -- audio signal to be panned

kazim -- azimuth angle of the virtual source

kelev (optional) -- elevation angle of the virtual source

kspread (optional) -- spreading of the virtual source (range 0 - 100).
If value is zero, conventional amplitude panning is used. When kspread
is increased, the number of loudspeakers used in panning increases. If
value is 100, the sound is applied to all loudspeakers.

vbap8 takes an input signal, asig, and distributes it among 8 outputs,
according to the controls kazim and kelev, and the configured
loudspeaker placement. If idim = 2, kelev is set to zero. The
distribution is performed using Vector Base Amplitude Panning (VBAP -
See reference). VBAP distributes the signal using loudspeaker data
configured with vbaplsinit. The signal is applied to, at most, two
loudspeakers in 2-D loudspeaker configurations, and three loudspeakers
in 3-D loudspeaker configurations. If the virtual source is panned
outside the region spanned by loudspeakers, the nearest loudspeakers are
used in panning.

  Warning

Please note that all vbap panning opcodes require the vbap system to be
initialized using vbaplsinit.


===========================================================================
vbap8move                                                         *vbap8move*

  Description

Distributes an audio signal among 8 channels with moving virtual sources.

  Syntax

ar1, ..., ar8 vbap8move asig, idur, ispread, ifldnum, ifld1 \
      [, ifld2] [...]

  Initialization

idur -- the duration over which the movement takes place.

ispread -- spreading of the virtual source (range 0 - 100). If value is
zero, conventional amplitude panning is used. When ispread is increased,
the number of loudspeakers used in panning increases. If value is 100,
the sound is applied to all loudspeakers.

ifldnum -- number of fields (absolute value must be 2 or larger). If
ifldnum is positive, the virtual source movement is a polyline specified
by given directions. Each transition is performed in an equal time
interval. If ifldnum is negative, specified angular velocities are
applied to the virtual source during specified relative time intervals
(see below).

ifld1, ifld2, ... -- azimuth angles or angular velocities, and relative
durations of movement phases (see below).

  Performance

asig -- audio signal to be panned

vbap8move allows the use of moving virtual sources. If ifldnum is
positive, the fields represent directions of virtual sources and equal
times, iazi1, [iele1,] iazi2, [iele2,], etc. The position of the virtual
source is interpolated between directions starting from the first
direction and ending at the last. Each interval is interpolated in time
that is fraction total_time / number_of_intervals of the duration of the
sound event.

If ifldnum is negative, the fields represent angular velocities and
equal times. The first field is, however, the starting direction, iazi1,
[iele1,] iazi_vel1, [iele_vel1,] iazi_vel2, [iele_vel2,] .... Each
velocity is applied to the note that is fraction total_time /
number_of_velocities of the duration of the sound event. If the
elevation of the virtual source becomes greater than 90 degrees or less
than 0 degrees, the polarity of angular velocity is changed. Thus the
elevational angular velocity produces a virtual source that moves up and
down between 0 and 90 degrees.

  Warning

Please note that all vbap panning opcodes require the vbap system to be
initialized using vbaplsinit.


===========================================================================
vbaplsinit                                                       *vbaplsinit*

  Description

Configures VBAP output according to loudspeaker parameters.

  Syntax

vbaplsinit idim, ilsnum [, idir1] [, idir2] [...] [, idir32]

  Initialization

idim -- dimensionality of loudspeaker array. Either 2 or 3. If the
dimension has a fractional part then that is used as the index of the
layout created (used in vbap, vbapz and vbapg only). The factional part
should be between .00 and .99.

ilsnum -- number of loudspeakers. In two dimensions, the number can vary
from 2 to 64. In three dimensions, the number can vary from 3 and 64.

idir1, idir2, ..., idir32 -- directions of loudspeakers. Number of
directions must be less than or equal to 16. In two-dimensional
loudspeaker positioning, idirn is the azimuth angle respective to nth
channel. In three-dimensional loudspeaker positioning, fields are the
azimuth and elevation angles of each loudspeaker consequently (azi1,
ele1, azi2, ele2, etc.).

  Note
In 2 dimensions the angle between two adjacent speakers must be less
than 179 degrees (170 degrees in earlier versions). This is a
restriction of the algorithm.

  Performance

VBAP distributes the signal using loudspeaker data configured with
vbaplsinit. The signal is applied to, at most, two loudspeakers in 2-D
loudspeaker configurations, and three loudspeakers in 3-D loudspeaker
configurations. If the virtual source is panned outside the region
spanned by loudspeakers, the nearest loudspeakers are used in panning.


===========================================================================
vbapz                                                                 *vbapz*

  Description

Writes a multi-channel audio signal to a ZAK array.

  Syntax

vbapz inumchnls, istartndx, asig, kazim [, kelev] [, kspread]

  Initialization

inumchnls -- number of channels to write to the ZA array. Must be in the
range 2 - 256.

istartndx -- first index or position in the ZA array to use

  Performance

asig -- audio signal to be panned

kazim -- azimuth angle of the virtual source

kelev (optional) -- elevation angle of the virtual source

kspread (optional) -- spreading of the virtual source (range 0 - 100).
If value is zero, conventional amplitude panning is used. When kspread
is increased, the number of loudspeakers used in panning increases. If
value is 100, the sound is applied to all loudspeakers.

The opcode vbapz is the multiple channel analog of the opcodes like
vbap4, working on inumchnls and using a ZAK array for output.

  Warning

Please note that all vbap panning opcodes require the vbap system to be
initialized using vbaplsinit.


===========================================================================
vbapzmove                                                         *vbapzmove*

  Description

Writes a multi-channel audio signal to a ZAK array with moving virtual
sources.

  Syntax

vbapzmove inumchnls, istartndx, asig, idur, ispread, ifldnum, ifld1, \
      ifld2, [...]

  Initialization

inumchnls -- number of channels to write to the ZA array. Must be in the
range 2 - 256.

istartndx -- first index or position in the ZA array to use

idur -- the duration over which the movement takes place.

ispread -- spreading of the virtual source (range 0 - 100). If value is
zero, conventional amplitude panning is used. When ispread is increased,
the number of loudspeakers used in panning increases. If value is 100,
the sound is applied to all loudspeakers.

ifldnum -- number of fields (absolute value must be 2 or larger). If
ifldnum is positive, the virtual source movement is a polyline specified
by given directions. Each transition is performed in an equal time
interval. If ifldnum is negative, specified angular velocities are
applied to the virtual source during specified relative time intervals
(see below).

ifld1, ifld2, ... -- azimuth angles or angular velocities, and relative
durations of movement phases (see below).

  Performance

asig -- audio signal to be panned

The opcode vbapzmove is the multiple channel analog of the opcodes like
vbap4move, working on inumchnls and using a ZAK array for output.

  Warning

Please note that all vbap panning opcodes require the vbap system to be
initialized using vbaplsinit.


===========================================================================
vcella                                                               *vcella*

  Description

Unidimensional Cellular Automata applied to Csound vectors

  Syntax

vcella ktrig, kreinit, ioutFunc, initStateFunc, \
      iRuleFunc, ielements, irulelen [, iradius]

  Initialization

ioutFunc - number of the table where the state of each cell is stored

initStateFunc - number of a table containig the inital states of each cell

iRuleFunc - number of a lookup table containing the rules

ielements - total number of cells

irulelen - total number of rules

iradius (optional) - radius of Cellular Automata. At present time CA
radius can be 1 or 2 (1 is the default)

  Performance

ktrig - trigger signal. Each time it is non-zero, a new generation of
cells is evaluated

kreinit - trigger signal. Each time it is non-zero, state of all cells
is forced to be that of initStateFunc.

vcella supports unidimensional cellular automata, where the state of
each cell is stored in ioutFunc. So ioutFunc is a vector containing
current state of each cell. This variant vector can be used together
with any other vector-based opcode, such as adsynt, vmap, vpowv etc.

initStateFunc is an input vector containing the inital value of the row
of cells, while iRuleFunc is an input vector containing the rules in the
form of a lookup table. Notice that initStateFunc and iRuleFunc can be
updated during the performance by means of other vector-based opcodes
(for example vcopy) in order to force to change rules and status at
performance time.

A new generation of cells is evaluated each time ktrig contains a
non-zero value. Also the status of all cells can be forced to assume the
status corresponding to the contents of initStateFunc each time kreinit
contains a non-zero value.

Radius of CA algorithm can be 1 or 2 (optional iradius arguement).


===========================================================================
vco                                                                     *vco*

  Description

Implementation of a band limited, analog modeled oscillator, based on
integration of band limited impulses. vco can be used to simulate a
variety of analog wave forms.

  Syntax

ares vco xamp, xcps, iwave, kpw [, ifn] [, imaxd] [, ileak] [, inyx] \
      [, iphs] [, iskip]

  Initialization

iwave -- determines the waveform:

  * iwave = 1 - sawtooth

  * iwave = 2 - square/PWM

  * iwave = 3 - triangle/saw/ramp

ifn (optional, default = 1) -- should be the table number of a of a
stored sine wave. Must point to a valid table which contains a sine
wave. Csound will report an error if this parameter is not set and table
1 doesn't exist.

imaxd (optional, default = 1) -- is the maximum delay time. A time of
1/ifqc may be required for the PWM and triangle waveform. To bend the
pitch down this value must be as large as 1/(minimum frequency).

ileak (optional, default = 0) -- if ileak is between zero and one (0 <
ileak < 1) then ileak is used as the leaky integrator value. Otherwise a
leaky integrator value of .999 is used for the saw and square waves and
.995 is used for the triangle wave. This can be used to “flatten” the
square wave or “straighten” the saw wave at low frequencies by setting
ileak to .99999 or a similar value. This should give a hollower sounding
square wave.

inyx (optional, default = .5) -- this is used to determine the number of
harmonics in the band limited pulse. All overtones up to sr * inyx will
be used. The default gives sr * .5 (sr/2). For sr/4 use inyx = .25. This
can generate a “fatter” sound in some cases.

iphs (optional, default = 0) -- this is a phase value. There is an
artifact (bug-like feature) in vco which occurs during the first half
cycle of the square wave which causes the waveform to be greater in
magnitude than all others. The value of iphs has an effect on this
artifact. In particular setting iphs to .5 will cause the first half
cycle of the square wave to resemble a small triangle wave. This may be
more desirable than the large wave artifact which is the current default.

iskip (optional, default = 0) -- if non zero skip the initialisation of
the filter. (New in Csound version 4.23f13 and 5.0)

  Performance

kpw -- determines either the pulse width (if iwave is 2) or the saw/ramp
character (if iwave is 3) The value of kpw should be greater than 0 and
less than 1. A value of 0.5 will generate either a square wave (if iwave
is 2) or a triangle wave (if iwave is 3).

xamp -- determines the amplitude

xcps -- is the frequency of the wave in cycles per second.


===========================================================================
vco2                                                                   *vco2*

  Description

vco2 is similar to vco. But the implementation uses pre-calculated
tables of band-limited waveforms (see also GEN30) rather than
integrating impulses. This opcode can be faster than vco (especially if
a low control-rate is used) and also allows better sound quality.
Additionally, there are more waveforms and oscillator phase can be
modulated at k-rate. The disadvantage is increased memory usage. For
more details about vco2 tables, see also vco2init and vco2ft.

  Syntax

ares vco2 kamp, kcps [, imode] [, kpw] [, kphs] [, inyx]

  Initialization

imode (optional, default=0) -- a sum of values representing the waveform
and its control values.

One may use any of the following values for imode:

  * 16: enable k-rate phase control (if set, kphs is a required k-rate
    parameter that allows phase modulation)

  * 1: skip initialization

One may use exactly one of these imode values to select the waveform to
be generated:

  * 14: user defined waveform -1 (requires using the vco2init opcode)

  * 12: triangle (no ramp, faster)

  * 10: square wave (no PWM, faster)

  * 8: 4 * x * (1 - x) (i.e. integrated sawtooth)

  * 6: pulse (not normalized)

  * 4: sawtooth / triangle / ramp

  * 2: square / PWM

  * 0: sawtooth

The default value for imode is zero, which means a sawtooth wave with no
k-rate phase control.

inyx (optional, default=0.5) -- bandwidth of the generated waveform, as
percentage (0 to 1) of the sample rate. The expected range is 0 to 0.5
(i.e. up to sr/2), other values are limited to the allowed range.

Setting inyx to 0.25 (sr/4), or 0.3333 (sr/3) can produce a “fatter”
sound in some cases, although it is more likely to reduce quality.

  Performance

ares -- the output audio signal.

kamp -- amplitude scale. In the case of a imode waveform value of 6 (a
pulse waveform), the actual output level can be a lot higher than this
value.

kcps -- frequency in Hz (should be in the range -sr/2 to sr/2).

kpw (optional) -- the pulse width of the square wave (imode waveform=2)
or the ramp characteristics of the triangle wave (imode waveform=4). It
is required only by these waveforms and ignored in all other cases. The
expected range is 0 to 1, any other value is wrapped to the allowed range.

  Warning

kpw must not be an exact integer value (e.g. 0 or 1) if a sawtooth /
triangle / ramp (imode waveform=4) is generated. In this case, the
recommended range is about 0.01 to 0.99. There is no such limitation for
a square/PWM waveform.

kphs (optional) -- oscillator phase (depending on imode, this can be
either an optional i-rate parameter that defaults to zero or required
k-rate). Similarly to kpw, the expected range is 0 to 1.

  Note

When a low control-rate is used, pulse width (kpw) and phase (kphs)
modulation is internally converted to frequency modulation. This allows
for faster processing and reduced artifacts. But in the case of very
long notes and continuous fast changes in kpw or kphs, the phase may
drift away from the requested value. In most cases, the phase error is
at most 0.037 per hour (assuming a sample rate of 44100 Hz).

This is a problem mainly in the case of pulse width (kpw), where it may
result in various artifacts. While future releases of vco2 may fix such
errors, the following work-arounds may also be of some help:

  * Use kpw values only in the range 0.05 to 0.95. (There are more
    artifacts around integer values)

  * Try to avoid modulating kpw by asymmetrical waveforms like a
    sawtooth wave. Relatively slow (<= 20 Hz) symmetrical modulation
    (e.g. sine or triangle), random splines (also slow), or a fixed
    pulse width is a lot less likely to cause synchronization problems.

  * In some cases, adding random jitter (for example: random splines
    with an amplitude of about 0.01) to kpw may also fix the problem.


===========================================================================
vco2ft                                                               *vco2ft*

  Description

vco2ft returns the function table number to be used for generating the
specified waveform at a given frequency. This function table number can
be used by any Csound opcode that generates a signal by reading function
tables (like oscilikt). The tables must be calculated by vco2init before
vco2ft is called and shared as Csound ftables (ibasfn).

  Syntax

kfn vco2ft kcps, iwave [, inyx]

  Initialization

iwave -- the waveform for which table number is to be selected. Allowed
values are:

  * 0: sawtooth

  * 1: 4 * x * (1 - x) (integrated sawtooth)

  * 2: pulse (not normalized)

  * 3: square wave

  * 4: triangle

Additionally, negative iwave values select user defined waveforms (see
also vco2init).

inyx (optional, default=0.5) -- bandwidth of the generated waveform, as
percentage (0 to 1) of the sample rate. The expected range is 0 to 0.5
(i.e. up to sr/2), other values are limited to the allowed range.

Setting inyx to 0.25 (sr/4), or 0.3333 (sr/3) can produce a “fatter”
sound in some cases, although it is more likely to reduce quality.

  Performance

kfn -- the ftable number, returned at k-rate.

kcps -- frequency in Hz, returned at k-rate. Zero and negative values
are allowed. However, if the absolute value exceeds sr/2 (or sr * inyx),
the selected table will contain silence.


===========================================================================
vco2ift                                                             *vco2ift*

  Description

vco2ift is the same as vco2ft, but works at i-time. It is suitable for
use with opcodes that expect an i-rate table number (for example, oscili).

  Syntax

ifn vco2ift icps, iwave [, inyx]

  Initialization

ifn -- the ftable number.

icps -- frequency in Hz. Zero and negative values are allowed. However,
if the absolute value exceeds sr/2 (or sr * inyx), the selected table
will contain silence.

iwave -- the waveform for which table number is to be selected. Allowed
values are:

  * 0: sawtooth

  * 1: 4 * x * (1 - x) (integrated sawtooth)

  * 2: pulse (not normalized)

  * 3: square wave

  * 4: triangle

Additionally, negative iwave values select user defined waveforms (see
also vco2init).

inyx (optional, default=0.5) -- bandwidth of the generated waveform, as
percentage (0 to 1) of the sample rate. The expected range is 0 to 0.5
(i.e. up to sr/2), other values are limited to the allowed range.

Setting inyx to 0.25 (sr/4), or 0.3333 (sr/3) can produce a “fatter”
sound in some cases, although it is more likely to reduce quality.


===========================================================================
vco2init                                                           *vco2init*

  Description

vco2init calculates tables for use by vco2 opcode. Optionally, it is
also possible to access these tables as standard Csound function tables.
In this case, vco2ft can be used to find the correct table number for a
given oscillator frequency.

In most cases, this opcode is called from the orchestra header. Using
vco2init in instruments is possible but not recommended. This is because
replacing tables during performance can result in a Csound crash if
other opcodes are accessing the tables at the same time.

Note that vco2init is not required for vco2 to work (tables are
automatically allocated by the first vco2 call, if not done yet),
however it can be useful in some cases:

  * Pre-calculate tables at orchestra load time. This is useful to avoid
    generating the tables during performance, which could interrupt
    real-time processing.

  * Share the tables as Csound ftables. By default, the tables can be
    accessed only by vco2.

  * Change the default parameters of tables (e.g. size) or use an
    user-defined waveform specified in a function table.

  Syntax

ifn vco2init iwave [, ibasfn] [, ipmul] [, iminsiz] [, imaxsiz] [, isrcft]

  Initialization

ifn -- the first free ftable number after the allocated tables. If
ibasfn was not specified, -1 is returned.

iwave -- sum of the following values selecting which waveforms are to be
calculated:

  * 16: triangle

  * 8: square wave

  * 4: pulse (not normalized)

  * 2: 4 * x * (1 - x) (integrated sawtooth)

  * 1: sawtooth

Alternatively, iwave can be set to a negative integer that selects an
user-defined waveform. This also requires the isrcft parameter to be
specified. vco2 can access waveform number -1. However, other
user-defined waveforms are usable only with vco2ft or vco2ift.

ibasfn (optional, default=-1) -- ftable number from which the table
set(s) can be accessed by opcodes other than vco2. This is required by
user defined waveforms, with the exception of -1. If this value is less
than 1, it is not possible to access the tables calculated by vco2init
as Csound function tables.

ipmul (optional, default=1.05) -- multiplier value for number of
harmonic partials. If one table has n partials, the next one will have n
* ipmul (at least n + 1). The allowed range for ipmul is 1.01 to 2. Zero
or negative values select the default (1.05).

iminsiz (optional, default=-1) -- minimum table size.

imaxsiz (optional, default=-1) -- maximum table size.

The actual table size is calculated by multiplying the square root of
the number of harmonic partials by iminsiz, rounding up the result to
the next power of two, and limiting this not to be greater than imaxsiz.

Both parameters, iminsiz and imaxsiz, must be power of two, and in the
allowed range. The allowed range is 16 to 262144 for iminsiz to up to
16777216 for imaxsiz. Zero or negative values select the default settings:

  * The minimum size is 128 for all waveforms except pulse (iwave=4).
    Its minimum size is 256.

  * The default maximum size is usually the minimum size multiplied by
    64, but not more than 16384 if possible. It is always at least the
    minimum size.

isrcft (optional, default=-1) -- source ftable number for user-defined
waveforms (if iwave < 0). isrcft should point to a function table
containing the waveform to be used for generating the table array. The
table size is recommended to be at least imaxsiz points. If iwave is not
negative (built-in waveforms are used), isrcft is ignored.

  Warning

The number and size of tables is not fixed. Orchestras should not depend
on these parameters, as they are subject to changes between releases.

If the selected table set already exists, it is replaced. If any opcode
is accessing the tables at the same time, it is very likely that a crash
will occur. This is why it is recommended to use vco2init only in the
orchestra header.

These tables should not be replaced/overwritten by GEN routines or the
ftgen opcode. Otherwise, unpredictable behavior or a Csound crash may
occur if vco2 is used. The first free ftable after the table array(s) is
returned in ifn.


===========================================================================
vcomb                                                                 *vcomb*

  Description

Variably reverberates an input signal with a “colored” frequency response.

  Syntax

ares vcomb asig, krvt, xlpt, imaxlpt [, iskip] [, insmps]

  Initialization

imaxlpt -- maximum loop time for klpt

iskip (optional, default=0) -- initial disposition of delay-loop data
space (cf. reson). The default value is 0.

insmps (optional, default=0) -- delay amount, as a number of samples.

  Performance

krvt -- the reverberation time (defined as the time in seconds for a
signal to decay to 1/1000, or 60dB down from its original amplitude).

xlpt -- variable loop time in seconds, same as ilpt in comb. Loop time
can be as large as imaxlpt.

This filter reiterates input with an echo density determined by loop
time xlpt. The attenuation rate is independent and is determined by
krvt, the reverberation time (defined as the time in seconds for a
signal to decay to 1/1000, or 60dB down from its original amplitude).
Output will appear only after ilpt seconds.


===========================================================================
vcopy                                                                 *vcopy*

  Description

Copies between two vectorial control signals

  Syntax

vcopy  ifn1, ifn2, kelements [, kdstoffset] [, ksrcoffset] [, kverbose]

  Initialization

ifn1 - number of the table where the vectorial signal will be copied
(destination)

ifn2 - number of the table hosting the vectorial signal to be copied
(source)

  Performance

kelements - number of elements of the vector

kdstoffset - index offset for the destination (ifn1) table (Default=0)

ksrcoffset - index offset for the source (ifn2) table (Default=0)

kverbose - Selects whether or not warnings are printed (Default=0)

vcopy copies kelements elements from ifn2 (starting from position
ksrcoffset) to ifn1 (starting from position kdstoffset). Useful to keep
old vector values, by storing them in another table.

Negative values for kdstoffset and ksrcoffset are acceptable. If
kdstoffset is negative, the out of range section of the vector will be
discarded. If kdstoffset is negative, the out of range elements will be
assumed to be 1 (i.e. the destination elements will not be changed). If
elements for the destination vector are beyond the size of the table
(including guard point), these elements are discarded (i.e. elements do
not wrap around the tables). If elements for the source vector are
beyond the table length, these elements are taken as 1 (i.e. the
destination vector will not be changed for these elements).

If the optional kverbose argument is different to 0, the opcode will
print warning messages every k-pass if table lengths are exceeded.

  Warning

Using the same table as source and destination table in versions earlier
than 5.04, might produce unexpected behavior, so use with care.

This opcode works at k-rate (this means that every k-pass the vectors
are copied). There's an i-rate version of this opcode called vcopy_i.

  Note

Please note that the elements argument has changed in version 5.03 from
i-rate to k-rate. This will change the opcode's behavior in the unusual
cases where the i-rate variable ielements is changed inside the
instrument, for example in:

instr 1
ielements  =        10
           vadd     1, 1, ielements
ielements  =        20
           vadd     2, 1, ielements
           turnoff
    endin

All these operators (vaddv, vsubv, vmultv, vdivv, vpowv, vexp, vcopy and
vmap) are designed to be used together with other opcodes that operate
with vectorial signals such as vcella, adsynt, adsynt2 etc.


===========================================================================
vcopy_i                                                             *vcopy_i*

  Description

Copies a vector from one table to another.

  Syntax

vcopy_i  ifn1, ifn2, ielements [,idstoffset, isrcoffset]

  Initialization

ifn1 - number of the table where the vectorial signal will be copied

ifn2 - number of the table hosting the vectorial signal to be copied

ielements - number of elements of the vector

idstoffset - index offset for destination table

isrcoffset - index offset for source table

  Performance

vcopy_i copies ielements elements from ifn2 (starting from position
isrcoffset) to ifn1 (starting from position idstoffset). Useful to keep
old vector values, by storing them in another table. This opcode is
exactly the same as vcopy but performs all the copying on the
intialization pass only.

Negative values for idstoffset and isrcoffset are acceptable. If
idstoffset is negative, the out of range section of the vector will be
discarded. If isrcoffset is negative, the out of range elements will be
assumed to be 0 (i.e. the destination elements will be set to 0). If
elements for the destination vector are beyond the size of the table
(including guard point), these elements are discarded (i.e. elements do
not wrap around the tables). If elements for the source vector are
beyond the table length, these elements are taken as 0 (i.e. the
destination vector elements will be 0).

  Warning

Using the same table as source and destination table in versions earlier
than 5.04, might produce unexpected behavior, so use with care.

All these operators (vaddv,vsubv,vmultv,vdivv,vpowv,vexp, vcopy and
vmap) are designed to be used together with other opcodes that operate
with vectorial signals such as vcella, adsynt, adsynt2 etc.


===========================================================================
vdelay                                                               *vdelay*

  Description

This is an interpolating variable time delay, it is not very different
from the existing implementation (deltapi), it is only easier to use.

  Syntax

ares vdelay asig, adel, imaxdel [, iskip]

  Initialization

imaxdel -- Maximum value of delay in milliseconds. If adel gains a value
greater than imaxdel it is folded around imaxdel. This should not happen.

iskip -- Skip initialization if present and non­zero

  Performance

With this unit generator it is possible to do Doppler effects or
chorusing and flanging.

asig -- Input signal.

adel -- Current value of delay in milliseconds. Note that linear
functions have no pitch change effects. Fast changing values of adel
will cause discontinuities in the waveform resulting noise.


===========================================================================
vdelay3                                                             *vdelay3*

  Description

vdelay3 is experimental. It is the same as vdelay except that it uses
cubic interpolation. (New in Version 3.50.)

  Syntax

ares vdelay3 asig, adel, imaxdel [, iskip]

  Initialization

imaxdel -- Maximum value of delay in milliseconds. If adel gains a value
greater than imaxdel it is folded around imaxdel. This should not happen.

iskip (optional) -- Skip initialization if present and non-zero.

  Performance

With this unit generator it is possible to do Doppler effects or
chorusing and flanging.

asig -- Input signal.

adel -- Current value of delay in milliseconds. Note that linear
functions have no pitch change effects. Fast changing values of adel
will cause discontinuities in the waveform resulting noise.


===========================================================================
vdelayx                                                             *vdelayx*

  Description

A variable delay opcode with high quality interpolation.

  Syntax

aout vdelayx ain, adl, imd, iws [, ist]

  Initialization

imd -- max. delay time (seconds)

iws -- interpolation window size (see below)

ist (optional) -- skip initialization if not zero

  Performance

aout -- output audio signal

ain -- input audio signal

adl -- delay time in seconds

This opcode uses high quality (and slow) interpolation, that is much
more accurate than the currently available linear and cubic
interpolation. The iws parameter sets the number of input samples used
for calculating one output sample (allowed values are any integer
multiply of 4 in the range 4 - 1024); higher values mean better quality
and slower speed.

  Notes

  * Delay time is measured in seconds (unlike in vdelay and vdelay3),
    and must be a-rate.

  * The minimum allowed delay is iws/2 samples.

  * Using the same variables as input and output is allowed in these
    opcodes.

  * In vdelayxw*, changing the delay time has some effects on output
    volume:

a = 1 / (1 + dt)

where a is the output gain, and dt is the change of delay time per seconds.

  * These opcodes are best used in the double-precision version of Csound.


===========================================================================
vdelayxq                                                           *vdelayxq*

  Description

A 4-channel variable delay opcode with high quality interpolation.

  Syntax

aout1, aout2, aout3, aout4 vdelayxq ain1, ain2, ain3, ain4, adl, imd, iws [, ist]

  Initialization

imd -- max. delay time (seconds)

iws -- interpolation window size (see below)

ist (optional) -- skip initialization if not zero

  Performance

aout1, aout2, aout3, aout4 -- output audio signals.

ain1, ain2, ain3, ain4 -- input audio signals.

adl -- delay time in seconds

This opcode uses high quality (and slow) interpolation, that is much
more accurate than the currently available linear and cubic
interpolation. The iws parameter sets the number of input samples used
for calculating one output sample (allowed values are any integer
multiply of 4 in the range 4 - 1024); higher values mean better quality
and slower speed.

The multichannel opcodes (eg. vdelayxq) allow delaying 2 or 4 variables
at once (stereo or quad signals); this is much more efficient than using
separate opcodes for each channel.

  Notes

  * Delay time is measured in seconds (unlike in vdelay and vdelay3),
    and must be a-rate.

  * The minimum allowed delay is iws/2 samples.

  * Using the same variables as input and output is allowed in these
    opcodes.

  * In vdelayxw*, changing the delay time has some effects on output
    volume:

a = 1 / (1 + dt)

where a is the output gain, and dt is the change of delay time per seconds.

  * These opcodes are best used in the double-precision version of Csound.


===========================================================================
vdelayxs                                                           *vdelayxs*

  Description

A stereo variable delay opcode with high quality interpolation.

  Syntax

aout1, aout2 vdelayxs ain1, ain2, adl, imd, iws [, ist]

  Initialization

imd -- max. delay time (seconds)

iws -- interpolation window size (see below)

ist (optional) -- skip initialization if not zero

  Performance

aout1, aout2 -- output audio signals

ain1, ain2 -- input audio signals

adl -- delay time in seconds

This opcode uses high quality (and slow) interpolation, that is much
more accurate than the currently available linear and cubic
interpolation. The iws parameter sets the number of input samples used
for calculating one output sample (allowed values are any integer
multiply of 4 in the range 4 - 1024); higher values mean better quality
and slower speed.

The multichannel opcodes (eg. vdelayxq) allow delaying 2 or 4 variables
at once (stereo or quad signals); this is much more efficient than using
separate opcodes for each channel.

  Notes

  * Delay time is measured in seconds (unlike in vdelay and vdelay3),
    and must be a-rate.

  * The minimum allowed delay is iws/2 samples.

  * Using the same variables as input and output is allowed in these
    opcodes.

  * In vdelayxw*, changing the delay time has some effects on output
    volume:

a = 1 / (1 + dt)

where a is the output gain, and dt is the change of delay time per seconds.

  * These opcodes are best used in the double-precision version of Csound.


===========================================================================
vdelayxw                                                           *vdelayxw*

  Description

Variable delay opcodes with high quality interpolation.

  Syntax

aout vdelayxw ain, adl, imd, iws [, ist]

  Initialization

imd -- max. delay time (seconds)

iws -- interpolation window size (see below)

ist (optional) -- skip initialization if not zero

  Performance

aout -- output audio signal

ain -- input audio signal

adl -- delay time in seconds

These opcodes use high quality (and slow) interpolation, that is much
more accurate than the currently available linear and cubic
interpolation. The iws parameter sets the number of input samples used
for calculating one output sample (allowed values are any integer
multiply of 4 in the range 4 - 1024); higher values mean better quality
and slower speed.

The vdelayxw opcodes change the position of the write tap in the delay
line (unlike all other delay ugens that move the read tap), and are most
useful for implementing Doppler effects where the position of the
listener is fixed, and the sound source is moving.

  Notes

  * Delay time is measured in seconds (unlike in vdelay and vdelay3),
    and must be a-rate.

  * The minimum allowed delay is iws/2 samples.

  * Using the same variables as input and output is allowed in these
    opcodes.

  * In vdelayxw*, changing the delay time has some effects on output
    volume:

a = 1 / (1 + dt)

where a is the output gain, and dt is the change of delay time per 
    seconds.

  * These opcodes are best used in the double-precision version of Csound.


===========================================================================
vdelayxwq                                                         *vdelayxwq*

  Description

Variable delay opcodes with high quality interpolation.

  Syntax

aout1, aout2, aout3, aout4 vdelayxwq ain1, ain2, ain3, ain4, adl, \
      imd, iws [, ist]

  Initialization

imd -- max. delay time (seconds)

iws -- interpolation window size (see below)

ist (optional) -- skip initialization if not zero

  Performance

ain1, ain2, ain3, ain4 -- input audio signals

aout1, aout2, aout3, aout4 -- output audio signals

adl -- delay time in seconds

These opcodes use high quality (and slow) interpolation, that is much
more accurate than the currently available linear and cubic
interpolation. The iws parameter sets the number of input samples used
for calculating one output sample (allowed values are any integer
multiply of 4 in the range 4 - 1024); higher values mean better quality
and slower speed.

The vdelayxw opcodes change the position of the write tap in the delay
line (unlike all other delay ugens that move the read tap), and are most
useful for implementing Doppler effects where the position of the
listener is fixed, and the sound source is moving.

The multichannel opcodes (eg. vdelayxq) allow delaying 2 or 4 variables
at once (stereo or quad signals); this is much more efficient than using
separate opcodes for each channel.

  Notes

  * Delay time is measured in seconds (unlike in vdelay and vdelay3),
    and must be a-rate.

  * The minimum allowed delay is iws/2 samples.

  * Using the same variables as input and output is allowed in these
    opcodes.

  * In vdelayxw*, changing the delay time has some effects on output
    volume:

a = 1 / (1 + dt)

where a is the output gain, and dt is the change of delay time per seconds.

  * These opcodes are best used in the double-precision version of Csound.


===========================================================================
vdelayxws                                                         *vdelayxws*

  Description

Variable delay opcodes with high quality interpolation.

  Syntax

aout1, aout2 vdelayxws ain1, ain2, adl, imd, iws [, ist]

  Initialization

imd -- max. delay time (seconds)

iws -- interpolation window size (see below)

ist (optional) -- skip initialization if not zero

  Performance

ain1, ain2 -- input audio signals

aout1, aout2 -- output audio signals

adl -- delay time in seconds

These opcodes use high quality (and slow) interpolation, that is much
more accurate than the currently available linear and cubic
interpolation. The iws parameter sets the number of input samples used
for calculating one output sample (allowed values are any integer
multiply of 4 in the range 4 - 1024); higher values mean better quality
and slower speed.

The vdelayxw opcodes change the position of the write tap in the delay
line (unlike all other delay ugens that move the read tap), and are most
useful for implementing Doppler effects where the position of the
listener is fixed, and the sound source is moving.

The multichannel opcodes (eg. vdelayxq) allow delaying 2 or 4 variables
at once (stereo or quad signals); this is much more efficient than using
separate opcodes for each channel.

  Notes

  * Delay time is measured in seconds (unlike in vdelay and vdelay3),
    and must be a-rate.

  * The minimum allowed delay is iws/2 samples.

  * Using the same variables as input and output is allowed in these
    opcodes.

  * In vdelayxw*, changing the delay time has some effects on output
    volume:

a = 1 / (1 + dt)

where a is the output gain, and dt is the change of delay time per seconds.

  * These opcodes are best used in the double-precision version of Csound.


===========================================================================
vdelayk                                                             *vdelayk*

  Description

Variable delay applied to a k-rate signal

  Syntax

kout vdelayk  ksig, kdel, imaxdel [, iskip, imode]

  Initialization

imaxdel - maximum value of delay in seconds.

iskip (optional) - Skip initialization if present and non zero.

imode (optional) - if non-zero it suppresses linear interpolation.
While, normally, interpolation increases the quality of a signal, it
should be suppressed if using vdelay with discrete control signals, such
as, for example, trigger signals.

  Performance

kout - delayed output signal

ksig - input signal

kdel - delay time in seconds can be varied at k-rate

vdelayk is similar to vdelay, but works at k-rate. It is designed to
delay control signals, to be used, for example, in algorithmic composition.


===========================================================================
vdivv                                                                 *vdivv*

  Description

Performs division between two vectorial control signals

  Syntax

vdivv  ifn1, ifn2, kelements [, kdstoffset] [, ksrcoffset] [,kverbose]

  Initialization

ifn1 - number of the table hosting the first vector to be processed

ifn2 - number of the table hosting the second vector to be processed

  Performance

kelements - number of elements of the two vectors

kdstoffset - index offset for the destination (ifn1) table (Default=0)

ksrcoffset - index offset for the source (ifn2) table (Default=0)

kverbose - Selects whether or not warnings are printed (Default=0)

vdivv divides two vectorial control signals, that is, each element of
ifn1 is divided by the corresponding element of ifn2. Each vectorial
signal is hosted by a table (ifn1 and ifn2). The number of elements
contained in both vectors must be the same.

The result is a new vectorial control signal that overrides old values
of ifn1. If you want to keep the old ifn1 vector, use vcopy_i opcode to
copy it in another table. You can use kdstoffset and ksrcoffset to
specify vectors in any location of the tables.

Negative values for kdstoffset and ksrcoffset are acceptable. If
kdstoffset is negative, the out of range section of the vector will be
discarded. If ksrcoffset is negative, the out of range elements will be
assumed to be 0 (i.e. the destination elements will be set to 0). If
elements for the destination vector are beyond the size of the table
(including guard point), these elements are discarded (i.e. elements do
not wrap around the tables). If elements for the source vector are
beyond the table length, these elements are taken as 0 (i.e. the
destination elements will be set to 0).

If the optional kverbose argument is different to 0, the opcode will
print warning messages every k-pass if table lengths are exceeded.

  Warning

Using the same table as source and destination table in versions earlier
than 5.04, might produce unexpected behavior, so use with care.

This opcode works at k-rate (this means that every k-pass the vectors
are divided). There's an i-rate version of this opcode called vdivv_i.

  Note

Please note that the elements argument has changed in version 5.03 from
i-rate to k-rate. This will change the opcode's behavior in the unusual
cases where the i-rate variable ielements is changed inside the
instrument, for example in:

instr 1
ielements  =        10
           vadd     1, 1, ielements
ielements  =        20
           vadd     2, 1, ielements
           turnoff
    endin

All these operators (vaddv,vsubv, vmultv, vdivv, vpowv, vexpv, vcopy and
vmap) are designed to be used together with other opcodes that operate
with vectorial signals such as vcella, adsynt, adsynt2 etc.


===========================================================================
vdivv_i                                                             *vdivv_i*

  Description

Performs division between two vectorial control signals at init time.

  Syntax

vdivv_i  ifn1, ifn2, ielements [, idstoffset] [, isrcoffset]

  Initialization

ifn1 - number of the table hosting the first vector to be processed

ifn2 - number of the table hosting the second vector to be processed

ielements - number of elements of the two vectors

idstoffset - index offset for the destination (ifn1) table (Default=0)

isrcoffset - index offset for the source (ifn2) table (Default=0)

  Performance

vdivv_i divides two vectorial control signals, that is, each element of
ifn1 is divided by the corresponding element of ifn2. Each vectorial
signal is hosted by a table (ifn1 and ifn2). The number of elements
contained in both vectors must be the same.

The result is a new vectorial control signal that overrides old values
of ifn1. If you want to keep the old ifn1 vector, use vcopy_i opcode to
copy it in another table. You can use idstoffset and isrcoffset to
specify vectors in any location of the tables.

Negative values for idstoffset and isrcoffset are acceptable. If
idstoffset is negative, the out of range section of the vector will be
discarded. If isrcoffset is negative, the out of range elements will be
assumed to be 1 (i.e. the destination elements will not be changed). If
elements for the destination vector are beyond the size of the table
(including guard point), these elements are discarded (i.e. elements do
not wrap around the tables). If elements for the source vector are
beyond the table length, these elements are taken as 1 (i.e. the
destination vector will not be changed for these elements).

  Warning

Using the same table as source and destination table in versions earlier
than 5.04, might produce unexpected behavior, so use with care.

This opcode works at init time. There's an k-rate version of this opcode
called vdivv.

All these operators (vaddv_i,vsubv_i,vmultv_i,vdivv_i,vpowv_i,vexpv_i,
vcopy and vmap) are designed to be used together with other opcodes that
operate with vectorial signals such as vcella, adsynt, adsynt2 etc.


===========================================================================
vecdelay                                                           *vecdelay*

  Description

Generate a sort of 'vectorial' delay

  Syntax

vecdelay  ifn, ifnIn, ifnDel, ielements, imaxdel [, iskip]

  Initialization

ifn - number of the table containing the output vector

ifnIn - number of the table containing the input vector

ifnDel - number of the table containing a vector whose elements contain
delay values in seconds

ielements - number of elements of the two vectors

imaxdel - Maximum value of delay in seconds.

iskip (optional) - initial disposition of delay-loop data space (see
reson). The default value is 0.

  Performance

vecdelay is similar to vdelay, but it works at k-rate and, instead of
delaying a single signal, it delays a vector. ifnIn is the input vector
of signals, ifn is the output vector of signals, and ifnDel is a vector
containing delay times for each element, expressed in seconds. Elements
of ifnDel can be updated at k-rate. Each single delay can be different
from that of the other elements, and can vary at k-rate. imaxdel sets
the maximum delay allowed for all elements of ifnDel.


===========================================================================
veloc                                                                 *veloc*

  Description

Get the velocity from a MIDI event.

  Syntax

ival veloc [ilow] [, ihigh]

  Initialization

ilow, ihigh -- low and hi ranges for mapping

  Performance

Get the MIDI byte value (0 - 127) denoting the velocity of the current
event.


===========================================================================
vexp                                                                   *vexp*

  Description

Performs power-of operations between a vector and a scalar

  Syntax

vexp  ifn, kval, kelements [, kdstoffset] [, kverbose]

  Initialization

ifn - number of the table hosting the vectorial signal to be processed

  Performance

kval - scalar operand to be processed

kelements - number of elements of the vector

kdstoffset - index offset for the destination table (Optional, default = 0)

kverbose - Selects whether or not warnings are printed (Default=0)

vexp rises kval to each element contained in a vector from table
ifn,starting from table index kdstoffset. This enables you to process a
specific section of a table by specifying the offset and the number of
elements to be processed. Offset is counted starting from 0, so if no
offset is specified (or set to 0), the table will be modified from the
beginning.

Note that this opcode runs at k-rate so the value of kval is processed
every control period. Use with care or you will end up with very large
(or small) numbers (or use vexp_i).

These opcodes (vadd, vmult, vpow and vexp) perform numeric operations
between a vectorial control signal (hosted by the table ifn), and a
scalar signal (kval). Result is a new vector that overrides old values
of ifn. All these opcodes work at k-rate.

Negative values for kdstoffset are valid. Elements from the vector that
are outside the table, will be discarded, and they will not wrap around
the table.

If the optional kverbose argument is different to 0, the opcode will
print warning messages every k-pass if table lengths are exceeded.

In all these opcodes, the resulting vectors are stored in ifn,
overriding the intial vectors. If you want to keep initial vector, use
vcopy or vcopy_i to copy it in another table. All these operators are
designed to be used together with other opcodes that operate with
vectorial signals such as vcella, adsynt, adsynt2, etc. They can also be
useful in conjunction with the spectral opcodes pvsftw and pvsftr.

  Note

Please note that the elements argument has changed in version 5.03 from
i-rate to k-rate. This will change the opcode's behavior in the unusual
cases where the i-rate variable ielements is changed inside the
instrument, for example in:

instr 1
ielements  =        10
           vadd     1, 1, ielements
ielements  =        20
           vadd     2, 1, ielements
           turnoff
    endin


===========================================================================
vexp_i                                                               *vexp_i*

  Description

Performs power-of operations between a vector and a scalar

  Syntax

vexp_i  ifn, ival, ielements[, idstoffset]

  Initialization

ifn - number of the table hosting the vectorial signal to be processed

ival - scalar operand to be processed

ielements - number of elements of the vector

ival - scalar value to be added

idstoffset - index offset for the destination table

  Performance

vexp_i rises ival to each element contained in a vector from table ifn,
starting from table index idstoffset. This enables you to process a
specific section of a table by specifying the offset and the number of
elements to be processed. Offset is counted starting from 0, so if no
offset is specified (or set to 0), the table will be modified from the
beginning.

Negative values for idstoffset are valid. Elements from the vector that
are outside the table, will be discarded, and they will not wrap around
the table.

This opcode runs only on initialization, there is a k-rate version of
this opcode called vexp.

In all these opcodes, the resulting vectors are stored in ifn,
overriding the initial vectors. If you want to keep initial vector, use
vcopy or vcopy_i to copy it in another table. All these operators are
designed to be used together with other opcodes that operate with
vectorial signals such as vcella, adsynt, adsynt2, etc. They can also be
useful in conjunction with the spectral opcodes pvsftw and pvsftr.


===========================================================================
vexpseg                                                             *vexpseg*

  Description

Generate exponential vectorial segments

  Syntax

vexpseg  ifnout, ielements, ifn1, idur1, ifn2 [, idur2, ifn3 [...]]

  Initialization

ifnout - number of table hosting output vectorial signal

ifn1 - starting vector

ifn2, ifn3,etc. - vector after idurx seconds

idur1 - duration in seconds of first segment.

idur2, idur3, etc. - duration in seconds of subsequent segments.

ielements - number of elements of vectors.

  Performance

These opcodes are similar to linseg and expseg, but operate with
vectorial signals instead of with scalar signals.

Output is a vectorial control signal hosted by ifnout (that must be
previously allocated), while each break-point of the envelope is
actually a vector of values. All break-points must contain the same
number of elements (ielements).

All these operators are designed to be used together with other opcodes
that operate with vectorial signals such as>, vcella, adsynt, adsynt2, etc.


===========================================================================
vexpv                                                                 *vexpv*

  Description

Performs exponential operations between two vectorial control signals

  Syntax

vexpv  ifn1, ifn2, kelements [, kdstoffset] [, ksrcoffset] [,kverbose]

  Initialization

ifn1 - number of the table hosting the first vector to be processed

ifn2 - number of the table hosting the second vector to be processed

  Performance

kelements - number of elements of the two vectors

kdstoffset - index offset for the destination (ifn1) table (Default=0)

ksrcoffset - index offset for the source (ifn2) table (Default=0)

kverbose - Selects whether or not warnings are printed (Default=0)

vexpv elevates each element of ifn2 to the corresponding element of
ifn1. Each vectorial signal is hosted by a table (ifn1 and ifn2). The
number of elements contained in both vectors must be the same.

The result is a new vectorial control signal that overrides old values
of ifn1. If you want to keep the old ifn1 vector, use vcopy_i opcode to
copy it in another table. You can use kdstoffset and ksrcoffset to
specify vectors in any location of the tables.

Negative values for kdstoffset and ksrcoffset are acceptable. If
kdstoffset is negative, the out of range section of the vector will be
discarded. If ksrcoffset is negative, the out of range elements will be
assumed to be 0 (i.e. the destination elements will be set to 1). If
elements for the destination vector are beyond the size of the table
(including guard point), these elements are discarded (i.e. elements do
not wrap around the tables). If elements for the source vector are
beyond the table length, these elements are taken as 0 (i.e. the
destination elements will be set to 1).

If the optional kverbose argument is different to 0, the opcode will
print warning messages every k-pass if table lengths are exceeded.

  Warning

Using the same table as source and destination table in versions earlier
than 5.04, might produce unexpected behavior, so use with care.

This opcode works at k-rate (this means that every k-pass the vectors
are processed). There's an i-rate version of this opcode called vexpv_i.

  Note

Please note that the elements argument has changed in version 5.03 from
i-rate to k-rate. This will change the opcode's behavior in the unusual
cases where the i-rate variable ielements is changed inside the
instrument, for example in:

instr 1
ielements  =        10
           vadd     1, 1, ielements
ielements  =        20
           vadd     2, 1, ielements
           turnoff
    endin

All these operators (vaddv, vsubv, vmultv, vdivv, vpowv, vexpv, vcopy
and vmap) are designed to be used together with other opcodes that
operate with vectorial signals such as vcella, adsynt, adsynt2 etc.


===========================================================================
vexpv_i                                                             *vexpv_i*

  Description

Performs exponential operations between two vectorial control signals at
init time.

  Syntax

vexpv_i  ifn1, ifn2, ielements [, idstoffset] [, isrcoffset]

  Initialization

ifn1 - number of the table hosting the first vector to be processed

ifn2 - number of the table hosting the second vector to be processed

ielements - number of elements of the two vectors

idstoffset - index offset for the destination (ifn1) table (Default=0)

isrcoffset - index offset for the source (ifn2) table (Default=0)

  Performance

vexpv_i elevates each element of ifn2 to the corresponding element of
ifn1. Each vectorial signal is hosted by a table (ifn1 and ifn2). The
number of elements contained in both vectors must be the same.

The result is a new vectorial control signal that overrides old values
of ifn1. If you want to keep the old ifn1 vector, use vcopy_i opcode to
copy it in another table. You can use idstoffset and isrcoffset to
specify vectors in any location of the tables.

Negative values for idstoffset and isrcoffset are acceptable. If
idstoffset is negative, the out of range section of the vector will be
discarded. If isrcoffset is negative, the out of range elements will be
assumed to be 1 (i.e. the destination elements will be set to 1). If
elements for the destination vector are beyond the size of the table
(including guard point), these elements are discarded (i.e. elements do
not wrap around the tables). If elements for the source vector are
beyond the table length, these elements are taken as 1 (i.e. the
destination vector elements will be set to 1).

  Warning

Using the same table as source and destination table in versions earlier
than 5.04, might produce unexpected behavior, so use with care.

This opcode works at init time. There's an k-rate version of this opcode
called vexpv.

All these operators (vaddv_i,vsubv_i,vmultv_i,vdivv_i,vpowv_i,vexpv_i,
vcopy and vmap) are designed to be used together with other opcodes that
operate with vectorial signals such as vcella, adsynt, adsynt2 etc.


===========================================================================
vibes                                                                 *vibes*

  Description

Audio output is a tone related to the striking of a metal block as found
in a vibraphone. The method is a physical model developed from Perry
Cook, but re-coded for Csound.

  Syntax

ares vibes kamp, kfreq, ihrd, ipos, imp, kvibf, kvamp, ivibfn, idec

  Initialization

ihrd -- the hardness of the stick used in the strike. A range of 0 to 1
is used. 0.5 is a suitable value.

ipos -- where the block is hit, in the range 0 to 1.

imp -- a table of the strike impulses. The file marmstk1.wav is a
suitable function from measurements and can be loaded with a GEN01
table. It is also available at
ftp://ftp.cs.bath.ac.uk/pub/dream/documentation/sounds/modelling/.

ivfn -- shape of tremolo, usually a sine table, created by a function

idec -- time before end of note when damping is introduced

  Performance

kamp -- Amplitude of note.

kfreq -- Frequency of note played.

kvibf -- frequency of tremolo in Hertz. Suggested range is 0 to 12

kvamp -- amplitude of the tremolo


===========================================================================
vibr                                                                   *vibr*

  Description

Easier-to-use user-controllable vibrato.

  Syntax

kout vibr kAverageAmp, kAverageFreq, ifn

  Initialization

ifn -- Number of vibrato table. It normally contains a sine or a
triangle wave.

  Performance

kAverageAmp -- Average amplitude value of vibrato

kAverageFreq -- Average frequency value of vibrato (in cps)

vibr is an easier-to-use version of vibrato. It has the same
generation-engine of vibrato, but the parameters corresponding to
missing input arguments are hard-coded to default values.


===========================================================================
vibrato                                                             *vibrato*

  Description

Generates a natural-sounding user-controllable vibrato.

  Syntax

kout vibrato kAverageAmp, kAverageFreq, kRandAmountAmp, kRandAmountFreq, kAmpMinRate, kAmpMaxRate, kcpsMinRate, kcpsMaxRate, ifn [, iphs

  Initialization

ifn -- Number of vibrato table. It normally contains a sine or a
triangle wave.

iphs -- (optional) Initial phase of table, expressed as a fraction of a
cycle (0 to 1). A negative value will cause phase initialization to be
skipped. The default value is 0.

  Performance

kAverageAmp -- Average amplitude value of vibrato

kAverageFreq -- Average frequency value of vibrato (in cps)

kRandAmountAmp -- Amount of random amplitude deviation

kRandAmountFreq -- Amount of random frequency deviation

kAmpMinRate -- Minimum frequency of random amplitude deviation segments
(in cps)

kAmpMaxRate -- Maximum frequency of random amplitude deviation segments
(in cps)

kcpsMinRate -- Minimum frequency of random frequency deviation segments
(in cps)

kcpsMaxRate -- Maximum frequency of random frequency deviation segments
(in cps)

vibrato outputs a natural-sounding user-controllable vibrato. The
concept is to randomly vary both frequency and amplitude of the
oscillator generating the vibrato, in order to simulate the
irregularities of a real vibrato.

In order to have a total control of these random variations, several
input arguments are present. Random variations are obtained by two
separated segmented lines, the first controlling amplitude deviations,
the second the frequency deviations. Average duration of each segment of
each line can be shortened or enlarged by the arguments kAmpMinRate,
kAmpMaxRate, kcpsMinRate, kcpsMaxRate, and the deviation from the
average amplitude and frequency values can be independently adjusted by
means of kRandAmountAmp and kRandAmountFreq.


===========================================================================
vincr                                                                 *vincr*

  Description

vincr increments one audio variable with another signal, i.e. it
accumulates output.

  Syntax

vincr accum, aincr

  Performance

accum -- audio-rate accumulator variable to be incremented

aincr -- incrementing signal

vincr (variable increment) and clear are intended to be used together.
vincr stores the result of the sum of two audio variables into the first
variable itself (which is intended to be used as an accumulator in
polyphony). The accumulator is typically a global variable that is used
to combine signals from several sources (different instruments or
instrument instances) for further processing (for example, via a global
effect that reads the accumulator) or for outputting the combined signal
by some means other than one of the out opcodes (eg. via the fout
opcode). After the accumulator is used, the accumulator variable should
be set to zero by means of the clear opcode (or it will explode).


===========================================================================
vlimit                                                               *vlimit*

  Description

Limits elements of vectorial control signals.

  Syntax

vlimit  ifn, kmin, kmax, ielements

  Initialization

ifn - number of the table hosting the vector to be processed

ielements - number of elements of the vector

  Performance

kmin - minimum threshold value

kmax - maximum threshold value

vlimit set lower and upper limits on each element of the vector they
process.

These opcodes are similar to limit, wrap and mirror, but operate with a
vectorial signal instead of with a scalar signal.

Result overrides old values of ifn1, if these are out of min/max
interval. If you want to keep input vector, use vcopy opcode to copy it
in another table.

All these opcodes are designed to be used together with other opcodes
that operate with vectorial signals such as vcella, adsynt, adsynt2 etc.


===========================================================================
vlinseg                                                             *vlinseg*

  Description

Generate linear vectorial segments

  Syntax

vlinseg  ifnout, ielements, ifn1, idur1, ifn2 [, idur2, ifn3 [...]]

  Initialization

ifnout - number of table hosting output vectorial signal

ifn1 - starting vector

ifn2,ifn3,etc. - vector after idurx seconds

idur1 - duration in seconds of first segment.

idur2, idur3, etc. - duration in seconds of subsequent segments.

ielements - number of elements of vectors.

  Performance

These opcodes are similar to linseg and expseg, but operate with
vectorial signals instead of with scalar signals.

Output is a vectorial control signal hosted by ifnout (that must be
previously allocated), while each break-point of the envelope is
actually a vector of values. All break-points must contain the same
number of elements (ielements).

All these operators are designed to be used together with other opcodes
that operate with vectorial signals such as vcella, adsynt, adsynt2, etc.


===========================================================================
vlowres                                                             *vlowres*

  Description

A bank of filters in which the cutoff frequency can be separated under
user control

  Syntax

ares vlowres asig, kfco, kres, iord, ksep

  Initialization

iord -- total number of filters (1 to 10)

  Performance

asig -- input signal

kfco -- frequency cutoff (not in Hz)

kres -- resonance amount

ksep -- frequency cutoff separation for each filter: the first filter
has a kfreq cutoff, the second has a kfreq + ksep and the third kfreq +
2*ksep and so on, depending on the number of filters.

vlowres (variable resonant lowpass filter) allows a variable response
curve in resonant filters. It can be thought of as a bank of lowpass
resonant filters, each with the same resonance, serially connected. The
frequency cutoff of each filter can vary with the kcfo and ksep parameters.


===========================================================================
vmap                                                                   *vmap*

  Description

Maps elements from a vector onto another according to the indexes of a
this vector.

  Syntax

vmap  ifn1, ifn2, ielements [,idstoffset, isrcoffset]

  Initialization

ifn1 - number of the table where the vectorial signal will be copied,
and which contains the mapping vector

ifn2 - number of the table hosting the vectorial signal to be copied

ielements - number of elements to process

idstoffset - index offset for destination table (ifn1)

isrcoffset - index offset for source table (ifn2)

  Performance

vmap maps elements of ifn2 according to the values of table ifn1.
Elements of ifn1 are treated as indexes of table ifn2, so element values
of ifn1 must not exceed the length of ifn2 table otherwise a Csound will
report an error. Elements of ifn1 are treated as integers, so any
fractional part will be truncated. There is no interpolation performed
on this operation.

In practice, what happens is that the elements of ifn1 are used as
indexes to ifn2, and then are replaced by the corresponding elements
from ifn2. ifn1 must be different from ifn2, otherwise the results are
unpredictable. Csound will produce an init error if they are not.

All these operators (vaddv, vsubv, vmultv, vdivv, vpowv, vexpv, vcopy
and vmap) are designed to be used together with other opcodes that
operate with vectorial signals such as, vcella, adsynt, adsynt2, etc.


===========================================================================
vmirror                                                             *vmirror*

  Description

'Reflects' elements of vectorial control signals on thresholds.

  Syntax

vmirror  ifn, kmin, kmax, ielements

  Initialization

ifn - number of the table hosting the vector to be processed

ielements - number of elements of the vector

  Performance

kmin - minimum threshold value

kmax - maximum threshold value

vmirror 'reflects' each element of corresponding vector if it exceeds
low or high thresholds.

These opcodes are similar to limit, wrap and mirror, but operate with a
vectorial signal instead of with a scalar signal.

Result overrides old values of ifn1, if these are out of min/max
interval. If you want to keep input vector, use vcopy opcode to copy it
in another table.

All these opcodes are designed to be used together with other opcodes
that operate with vectorial signals such as, vcella, adsynt, adsynt2 etc.


===========================================================================
vmult                                                                 *vmult*

  Description

Multiplies a vector in a table by a scalar value.

  Syntax

vmult  ifn, kval, kelements [, kdstoffset] [, kverbose]

  Initialization

ifn - number of the table hosting the vectorial signal to be processed

  Performance

kval - scalar value to be multiplied

kelements - number of elements of the vector

kdstoffset - index offset for the destination table (Optional, default = 0)

kverbose - Selects whether or not warnings are printed (Default=0)

vmult multiplies each element of the vector contained in the table ifn
by kval, starting from table index kdstoffset. This enables you to
process a specific section of a table by specifying the offset and the
number of elements to be processed. Offset is counted starting from 0,
so if no offset is specified (or set to 0), the table will be modified
from the beginning.

Note that this opcode runs at k-rate so the value of kval is multiplied
every control period. Use with care or you will end up with very large
numbers (or use vmult_i).

These opcodes (vadd, vmult, vpow and vexp) perform numeric operations
between a vectorial control signal (hosted by the table ifn), and a
scalar signal (kval). Result is a new vector that overrides old values
of ifn. All these opcodes work at k-rate.

Negative values for kdstoffset are valid. Elements from the vector that
are outside the table, will be discarded, and they will not wrap around
the table.

If the optional kverbose argument is different to 0, the opcode will
print warning messages every k-pass if table lengths are exceeded.

In all these opcodes, the resulting vectors are stored in ifn,
overriding the initial vectors. If you want to keep initial vector, use
vcopy or vcopy_i to copy it in another table. All these operators are
designed to be used together with other opcodes that operate with
vectorial signals such as vcella, adsynt, adsynt2, etc. They can also be
useful in conjunction with the spectral opcodes pvsftw and pvsftr.

  Note

Please note that the elements argument has changed in version 5.03 from
i-rate to k-rate. This will change the opcode's behavior in the unusual
cases where the i-rate variable ielements is changed inside the
instrument, for example in:

instr 1
ielements  =        10
           vadd     1, 1, ielements
ielements  =        20
           vadd     2, 1, ielements
           turnoff
    endin


===========================================================================
vmult_i                                                             *vmult_i*

  Description

Multiplies a vector in a table by a scalar value.

  Syntax

vmult_i  ifn, ival, ielements [, idstoffset]

  Initialization

ifn - number of the table hosting the vectorial signal to be processed

ival - scalar value to be multiplied

ielements - number of elements of the vector

idstoffset - index offset for the destination table

  Performance

vmult_i multiplies each element of the vector contained in the table ifn
by ival, starting from table index idstoffset. This enables you to
process a specific section of a table by specifying the offset and the
number of elements to be processed. Offset is counted starting from 0,
so if no offset is specified (or set to 0), the table will be modified
from the beginning.

This opcode runs only on initialization, there is a k-rate version of
this opcode called vmult.

Negative values for idstoffset are valid. Elements from the vector that
are outside the table, will be discarded, and they will not wrap around
the table.

In all these opcodes, the resulting vectors are stored in ifn,
overriding the intial vectors. If you want to keep initial vector, use
vcopy or vcopy_i to copy it in another table. All these operators are
designed to be used together with other opcodes that operate with
vectorial signals such as , vcella, adsynt, adsynt2, etc. They can also
be useful in conjunction with the spectral opcodes pvsftw and pvsftr.


===========================================================================
vmultv                                                               *vmultv*

  Description

Performs mutiplication between two vectorial control signals

  Syntax

vmultv  ifn1, ifn2, kelements [, kdstoffset] [, ksrcoffset] [,kverbose]

  Initialization

ifn1 - number of the table hosting the first vector to be processed

ifn2 - number of the table hosting the second vector to be processed

  Performance

kelements - number of elements of the two vectors

kdstoffset - index offset for the destination (ifn1) table (Default=0)

ksrcoffset - index offset for the source (ifn2) table (Default=0)

kverbose - Selects whether or not warnings are printed (Default=0)

vmultv multiplies two vectorial control signals, that is, each element
of the first vector is processed (only) with the corresponding element
of the other vector. Each vectorial signal is hosted by a table (ifn1
and ifn2). The number of elements contained in both vectors must be the
same.

The Result is a new vectorial control signal that overrides old values
of ifn1. If you want to keep the old ifn1 vector, use vcopy_i opcode to
copy it in another table. You can use kdstoffset and ksrcoffset to
specify vectors in any location of the tables.

Negative values for kdstoffset and ksrcoffset are acceptable. If
kdstoffset is negative, the out of range section of the vector will be
discarded. If ksrcoffset is negative, the out of range elements will be
assumed to be 1 (i.e. the destination elements will not be changed). If
elements for the destination vector are beyond the size of the table
(including guard point), these elements are discarded (i.e. elements do
not wrap around the tables). If elements for the source vector are
beyond the table length, these elements are taken as 1 (i.e. the
destination vector will not be changed for these elements).

If the optional kverbose argument is different to 0, the opcode will
print warning messages every k-pass if table lengths are exceeded.

  Warning

Using the same table as source and destination table in versions earlier
than 5.04, might produce unexpected behavior, so use with care.

This opcode works at k-rate (this means that every k-pass the vectors
are multiplied). There's an i-rate version of this opcode called vmultv_i.

  Note

Please note that the elements argument has changed in version 5.03 from
i-rate to k-rate. This will change the opcode's behavior in the unusual
cases where the i-rate variable ielements is changed inside the
instrument, for example in:

instr 1
ielements  =        10
           vadd     1, 1, ielements
ielements  =        20
           vadd     2, 1, ielements
           turnoff
    endin

All these operators (vaddv, vsubv, vmultv, vdivv, vpowv, vexpv, vcopy
and vmap) are designed to be used together with other opcodes that
operate with vectorial signals such as vcella, adsynt, adsynt2 etc.


===========================================================================
vmultv_i                                                           *vmultv_i*

  Description

Performs mutiplication between two vectorial control signals at init time.

  Syntax

vmultv_i  ifn1, ifn2, ielements [, idstoffset] [, isrcoffset]

  Initialization

ifn1 - number of the table hosting the first vector to be processed

ifn2 - number of the table hosting the second vector to be processed

ielements - number of elements of the two vectors

idstoffset - index offset for the destination (ifn1) table (Default=0)

isrcoffset - index offset for the source (ifn2) table (Default=0)

  Performance

vmultv_i multiplies two vectorial control signals, that is, each element
of the first vector is processed (only) with the corresponding element
of the other vector. Each vectorial signal is hosted by a table (ifn1
and ifn2). The number of elements contained in both vectors must be the
same.

The result is a new vectorial control signal that overrides old values
of ifn1. If you want to keep the old ifn1 vector, use vcopy_i opcode to
copy it in another table. You can use idstoffset and isrcoffset to
specify vectors in any location of the tables.

Negative values for idstoffset and isrcoffset are acceptable. If
idstoffset is negative, the out of range section of the vector will be
discarded. If isrcoffset is negative, the out of range elements will be
assumed to be 1 (i.e. the destination elements will not be changed). If
elements for the destination vector are beyond the size of the table
(including guard point), these elements are discarded (i.e. elements do
not wrap around the tables). If elements for the source vector are
beyond the table length, these elements are taken as 1 (i.e. the
destination vector will not be changed for these elements).

  Warning

Using the same table as source and destination table in versions earlier
than 5.04, might produce unexpected behavior, so use with care.

This opcode works at init time. There's an k-rate version of this opcode
called vmultv.

All these operators (vaddv_i,vsubv_i,vmultv_i,vdivv_i,vpowv_i,vexpv_i,
vcopy and vmap) are designed to be used together with other opcodes that
operate with vectorial signals such as vcella, adsynt, adsynt2 etc.


===========================================================================
voice                                                                 *voice*

  Description

An emulation of a human voice.

  Syntax

ares voice kamp, kfreq, kphoneme, kform, kvibf, kvamp, ifn, ivfn

  Initialization

ifn, ivfn -- two table numbers containing the carrier waveform and the
vibrato waveform. The files impuls20.aiff, ahh.aiff, eee.aiff, or
ooo.aiff are suitable for the first of these, and a sine wave for the
second. These files are available from
ftp://ftp.cs.bath.ac.uk/pub/dream/documentation/sounds/modelling/.

  Performance

kamp -- Amplitude of note.

kfreq -- Frequency of note played. It can be varied in performance.

kphoneme -- an integer in the range 0 to 16, which select the formants
for the sounds:

  * “eee”, “ihh”, “ehh”, “aaa”,

  * “ahh”, “aww”, “ohh”, “uhh”,

  * “uuu”, “ooo”, “rrr”, “lll”,

  * “mmm”, “nnn”, “nng”, “ngg”.

At present the phonemes

  * “fff”, “sss”, “thh”, “shh”,

  * “xxx”, “hee”, “hoo”, “hah”,

  * “bbb”, “ddd”, “jjj”, “ggg”,

  * “vvv”, “zzz”, “thz”, “zhh”

are not available (!)

kform -- Gain on the phoneme. values 0.0 to 1.2 recommended.

kvibf -- frequency of vibrato in Hertz. Suggested range is 0 to 12

kvamp -- amplitude of the vibrato


===========================================================================
vosim                                                                 *vosim*

  Description

This opcode produces a simple vocal simulation based on glottal pulses
with formant characteristics. Output is a series of sound events, where
each event is composed of a burst of squared sine pulses followed by
silence. The VOSIM (VOcal SIMulation) synthesis method was developed by
Kaegi and Tempelaars in the 1970's.

  Syntax

ar vosim kamp, kFund, kForm, kDecay, kPulseCount, kPulseFactor, ifn [, iskip]

  Intialization

ifn - a sound table, normally containing half a period of a sinewave,
squared (see notes below).

iskip - (optional) Skip initialization, for tied notes.

  Performance

ar - output signal. Note that the output is usually unipolar - positive
only.

kamp - output amplitude, the peak amplitude of the first pulse in each
burst.

kFund - fundamental pitch, in Herz. Each event is 1/kFund seconds long.

kForm - formant center frequency. Length of each pulse in the burst is
1/kForm seconds.

kDecay - a dampening factor from pulse to pulse. This is subtracted from
amplitude on each new pulse.

kPulseCount - number of pulses in the burst part of each event.

kPulseFactor - the pulse width is multiplied by this value at each new
pulse. This results in formant sweeping. If factor is < 1.0, the formant
sweeps up, if > 1.0 each new pulse is longer, so the formant sweeps
down. The final pitch of the formant is kForm * pow(kPulseFactor,
kPulseCount)

The output of vosim is a series of sound events, where each event is
composed of a burst of squared sine pulses followed by silence. The
total duration of the events determines fundamental frequency. The
length of each single pulse in the squared-sine bursts produce a formant
frequency band. The width of the formant is determined by rate of
silence to pulses (see below). The final result is also shaped by the
dampening factor from pulse to pulse.

A small practical problem in using this opcode is that no GEN function
will create a squared sine wave out of the box. Something like the
following can be used to create the appropriate table from the score.

; use GEN09 to create half a sine in table 17

f 17 time size 9  0.5  1 0

; run instr 101 on table 17 for a single init-pass

i 101 0 0 17

It can also be done with an instrument writing to an f-table in the
orchestra:

        ; square each point in table #p4. This should be run as init-only, just once in the performance.

instr 101

index tableng p4

index = index - 1  ; start from last point
loop:

ival table index, p4
ival = ival * ival
tableiw ival, index, p4
index = index - 1
if index < 0 igoto endloop
            igoto loop
endloop:
endin

  Parameter Limits

The count of pulses multiplied by pulse width should fit in the event
length (1/kFund). If this is not fulfilled, the algorithm does not
break, we just do not start any pulses that would outlast the event.
This might introduce a silence at end of event even if none was
intended. In consequence, kForm should be higher than kFund, otherwise
only silence is output.

Vosim was created to emulate voice sounds using a model of glottal
pulse. Rich sounds can be created by combining several instances of
vosim with different parameters. One drawback is that the signal is not
band-limited. But as the authors point out, attenuation of high-pitch
components is -60 dB at 6 times the fundamental frequency. The signal
can also be changed by changing the source signal in the lookup table.
The technique has historical interest, and can produce rich sound very
cheaply (each sample requires only a table lookup and a single
multiplication for attenuation).

As stated, formant bandwidth depends on the ratio between pulse burst
and silence in an event. But this is not an independent parameter: The
fundamental decides event length, and formant center defines the pulse
length. It is therefore impossible to guarantee a specific burst/silence
ratio, since the burst length has to be an integer multiple of pulse
length. The decay of pulses can be used to smooth the transition from N
to N+/-1 pulses, but there will still be steps in the spectral profile
of output. The example code below shows one approach to this.

All input parameters are k-rate. The input parameters are only used to
set up each new event (or grain). Event amplitude is fixed for each
event at initialization. In normal parameter ranges, when ksmps <500,
the k-rate parameters are updated more often than events are created. In
any case, no wide-band noise will be injected in the system due to
k-rate inputs being updated less often than they are read, but some
other artefacts could be created.

The opcode should behave reasonably in the face of all user inputs. Some
details:

 1. kFund < 0: This is forced to positive - no point in "reversed" events.

 2. kFund == 0: This leads to "infinite" length event, ie a pulse burst
    followed by very long indefinite silence.

 3. kForm == 0: This leads to infinite length pulse, so no pulses are
    generated (i.e. silence).

 4. kForm < 0: Table is read backward. If table is symmetric, kform and
    -kform should give bit-identical outputs.

 5. kPulseFactor == 0: Second pulse onwards is zero. See (c).

 6. kPulseFactor < 0: Pulses alternately read table forward and reversed.

With asymmetric pulse table there may be some use for negative kForm or
negative kPulseFactor.


===========================================================================
vphaseseg                                                         *vphaseseg*

  Description

vphaseseg allows one-dimensional HVS (Hyper-Vectorial Synthesis).

  Syntax

vphaseseg kphase, ioutab, ielems, itab1,idist1,itab2 \
      [,idist2,itab3, ... ,idistN-1,itabN]

  Initialization

ioutab - number of output table.

ielem - number of elements to process

itab1,...,itabN - breakpoint table numbers

idist1,...,idistN-1 - distances between breakpoints in percentage values

  Performance

kphase - phase pointer

vphaseseg returns the coordinates of section points of an N-dimensional
space path. The coordinates of section points are stored into an output
table. The number of dimensions of the N-dimensional space is determined
by the ielem argument that is equal to N and can be set to any number.
To define the path, user have to provide a set of points of the
N-dimensional space, called break-points. Coordinates of each
break-point must be contained by a different table. The number of
coordinates to insert in each break-point table must obviously equal to
ielem argument. There can be any number of break-point tables filled by
the user.

Hyper-Vectorial Synthesis actually deals with two kinds of spaces. The
first space is the N-dimensional space in which the path is defined,
this space is called time-variant parameter space (or SPACE A). The path
belonging to this space is covered by moving a point into the second
space that normally has a number of dimensions smaller than the first.
Actually, the point in motion is the projection of corresponding point
of the N-dimensional space (could also be considered a section of the
path). The second space is called user-pointer-motion space (or SPACE B)
and, in the case of vphaseseg opcode, has only ONE DIMENSION. Space B is
covered by means of kphase argument (that is a sort of path pointer),
and its range is 0 to 1. The output corresponding to current pointer
value is stored in ioutab table, whose data can be afterwards used to
control any syntesis parameters.

In vphaseseg, each break-point is separated from the other by a distance
expressed in percentage, where all the path length is equal to the sum
of all distances. So distances between breakpoints can be different,
differently from kinds of HVS in which space B has more than one
dimension, in these cases distance between break-points MUST be THE SAME
for all intervals.


===========================================================================
vport                                                                 *vport*

  Description

Generate a sort of 'vectorial' portamento

  Syntax

vport ifn, khtime, ielements [, ifnInit]

  Initialization

ifn - number of the table containing the output vector

ielements - number of elements of the two vectors

ifnInit (optional) - number of the table containing a vector whose
elements contain initial portamento values.

  Performance

vport is similar to port, but operates with vectorial signals, instead
of with scalar signals. Each vector element is treated as an independent
control signal. Input and output vectors are placed in the same table
and output vector overrides input vector. If you want to keep input
vector, use vcopy opcode to copy it in another table.


===========================================================================
vpow                                                                   *vpow*

  Description

Raises each element of a vector to a scalar power.

  Syntax

vpow  ifn, kval, kelements [, kdstoffset] [, kverbose]

  Initialization

ifn - number of the table hosting the vectorial signal to be processed

  Performance

kval - scalar value to which the elements of ifn will be raised

kelements - number of elements of the vector

kdstoffset - index offset for the destination table (Optional, default = 0)

kverbose - Selects whether or not warnings are printed (Default=0)

vpow raises each element of the vector contained in the table ifn to the
power of kval, starting from table index kdstoffset. This enables you to
process a specific section of a table by specifying the offset and the
number of elements to be processed. Offset is counted starting from 0,
so if no offset is specified (or set to 0), the table will be modified
from the beginning.

Note that this opcode runs at k-rate so the value of kval is processed
every control period. Use with care or you will end up with very large
(or small) numbers (or use vpow_i).

These opcodes (vadd, vmult, vpow and vexp) perform numeric operations
between a vectorial control signal (hosted by the table ifn), and a
scalar signal (kval). Result is a new vector that overrides old values
of ifn. All these opcodes work at k-rate.

Negative values for kdstoffset are valid. Elements from the vector that
are outside the table, will be discarded, and they will not wrap around
the table.

If the optional kverbose argument is different to 0, the opcode will
print warning messages every k-pass if table lengths are exceeded.

In all these opcodes, the resulting vectors are stored in ifn,
overriding the intial vectors. If you want to keep initial vector, use
vcopy or vcopy_i to copy it in another table. All these operators are
designed to be used together with other opcodes that operate with
vectorial signals such as vcella, adsynt, adsynt2, etc. They can also be
useful in conjunction with the spectral opcodes pvsftw and pvsftr.

  Note

Please note that the elements argument has changed in version 5.03 from
i-rate to k-rate. This will change the opcode's behavior in the unusual
cases where the i-rate variable ielements is changed inside the
instrument, for example in:

instr 1
ielements  =        10
           vadd     1, 1, ielements
ielements  =        20
           vadd     2, 1, ielements
           turnoff
    endin


===========================================================================
vpow_i                                                               *vpow_i*

  Description

Raises each element of a vector to a scalar power

  Syntax

vpow_i  ifn, ival, ielements [, idstoffset]

  Initialization

ifn - number of the table hosting the vectorial signal to be processed

ielements - number of elements of the vector

ival - scalar value to which the elements of ifn will be raised

idstoffset - index offset for the destination table

  Performance

vpow_i elevates each element of the vector contained in the table ifn to
the power of ival, starting from table index idstoffset. This enables
you to process a specific section of a table by specifying the offset
and the number of elements to be processed. Offset is counted starting
from 0, so if no offset is specified (or set to 0), the table will be
modified from the beginning.

This opcode runs only on initialization, there is a k-rate version of
this opcode called vpow.

Negative values for idstoffset are valid. Elements from the vector that
are outside the table, will be discarded, and they will not wrap around
the table.

In all these opcodes, the resulting vectors are stored in ifn,
overriding the intial vectors. If you want to keep initial vector, use
vcopy or vcopy_i to copy it in another table. All these operators are
designed to be used together with other opcodes that operate with
vectorial signals such as vcella, adsynt, adsynt2, etc. They can also be
useful in conjunction with the spectral opcodes pvsftw and pvsftr.


===========================================================================
vpowv                                                                 *vpowv*

  Description

Performs power-of operations between two vectorial control signals

  Syntax

vpowv ifn1, ifn2, kelements [, kdstoffset] [, ksrcoffset] [,kverbose]

  Initialization

ifn1 - number of the table hosting the first vector to be processed

ifn2 - number of the table hosting the second vector to be processed

  Performance

kelements - number of elements of the two vectors

kdstoffset - index offset for the destination (ifn1) table (Default=0)

ksrcoffset - index offset for the source (ifn2) table (Default=0)

kverbose - Selects whether or not warnings are printed (Default=0)

vpowv raises each element of ifn1 to the corresponding element of ifn2.
Each vectorial signal is hosted by a table (ifn1 and ifn2). The number
of elements contained in both vectors must be the same.

The result is a new vectorial control signal that overrides old values
of ifn1. If you want to keep the old ifn1 vector, use vcopy_i opcode to
copy it in another table. You can use kdstoffset and ksrcoffset to
specify vectors in any location of the tables.

Negative values for kdstoffset and ksrcoffset are acceptable. If
kdstoffset is negative, the out of range section of the vector will be
discarded. If ksrcoffset is negative, the out of range elements will be
assumed to be 1 (i.e. the destination elements will not be changed). If
elements for the destination vector are beyond the size of the table
(including guard point), these elements are discarded (i.e. elements do
not wrap around the tables). If elements for the source vector are
beyond the table length, these elements are taken as 1 (i.e. the
destination vector will not be changed for these elements).

If the optional kverbose argument is different to 0, the opcode will
print warning messages every k-pass if table lengths are exceeded.

  Warning

Using the same table as source and destination table in versions earlier
than 5.04, might produce unexpected behavior, so use with care.

This opcode works at k-rate (this means that every k-pass the vectors
are processed). There's an i-rate version of this opcode called vpowv_i.

  Note

Please note that the elements argument has changed in version 5.03 from
i-rate to k-rate. This will change the opcode's behavior in the unusual
cases where the i-rate variable ielements is changed inside the
instrument, for example in:

instr 1
ielements  =        10
           vadd     1, 1, ielements
ielements  =        20
           vadd     2, 1, ielements
           turnoff
    endin

All these operators (vaddv, vsubv, vmultv, vdivv, vpowv, vexpv, vcopy
and vmap) are designed to be used together with other opcodes that
operate with vectorial signals such as vcella, adsynt, adsynt2, etc.


===========================================================================
vpowv_i                                                             *vpowv_i*

  Description

Performs power-of operations between two vectorial control signals at
init time.

  Syntax

vpowv_i ifn1, ifn2, ielements [, idstoffset] [, isrcoffset]

  Initialization

ifn1 - number of the table hosting the first vector to be processed

ifn2 - number of the table hosting the second vector to be processed

ielements - number of elements of the two vectors

idstoffset - index offset for the destination (ifn1) table

isrcoffset - index offset for the source (ifn2) table

  Performance

vpowv_i raises each element of ifn1 to the corresponding element of
ifn2. Each vectorial signal is hosted by a table (ifn1 and ifn2). The
number of elements contained in both vectors must be the same.

The result is a new vectorial control signal that overrides old values
of ifn1. If you want to keep the old ifn1 vector, use vcopy_i opcode to
copy it in another table. You can use idstoffset and isrcoffset to
specify vectors in any location of the tables.

Negative values for idstoffset and isrcoffset are acceptable. If
idstoffset is negative, the out of range section of the vector will be
discarded. If isrcoffset is negative, the out of range elements will be
assumed to be 1 (i.e. the destination elements will not be changed). If
elements for the destination vector are beyond the size of the table
(including guard point), these elements are discarded (i.e. elements do
not wrap around the tables). If elements for the source vector are
beyond the table length, these elements are taken as 1 (i.e. the
destination vector will not be changed for these elements).

  Warning

Using the same table as source and destination table in versions earlier
than 5.04, might produce unexpected behavior, so use with care.

This opcode works at init time. There's an k-rate version of this opcode
called vpowv.

All these operators (vaddv_i,vsubv_i,vmultv_i,vdivv_i,vpowv_i,vexpv_i,
vcopy and vmap) are designed to be used together with other opcodes that
operate with vectorial signals such as vcella, adsynt, adsynt2 etc.


===========================================================================
vpvoc                                                                 *vpvoc*

  Description

Implements signal reconstruction using an fft-based phase vocoder and an
extra envelope.

  Syntax

ares vpvoc ktimpnt, kfmod, ifile [, ispecwp] [, ifn]

  Initialization

ifile -- the pvoc number (n in pvoc.n) or the name in quotes of the
analysis file made using pvanal. (See pvoc.)

ispecwp (optional, default=0) -- if non-zero, attempts to preserve the
spectral envelope while its frequency content is varied by kfmod. The
default value is zero.

ifn (optional, default=0) -- optional function table containing control
information for vpvoc. If ifn = 0, control is derived internally from a
previous tableseg or tablexseg unit. Default is 0. (New in Csound
version 3.59)

  Performance

ktimpnt -- The passage of time, in seconds, through the analysis file.
ktimpnt must always be positive, but can move forwards or backwards in
time, be stationary or discontinuous, as a pointer into the analysis file.

kfmod -- a control-rate transposition factor: a value of 1 incurs no
transposition, 1.5 transposes up a perfect fifth, and .5 down an octave.

This implementation of pvoc was orignally written by Dan Ellis. It is
based in part on the system of Mark Dolson, but the pre-analysis concept
is new. The spectral extraction and amplitude gating (new in Csound
version 3.56) were added by Richard Karpen based on functions in
SoundHack by Tom Erbe.

vpvoc is identical to pvoc except that it takes the result of a previous
tableseg or tablexseg and uses the resulting function table (passed
internally to the vpvoc), as an envelope over the magnitudes of the
analysis data channels. Optionally, a table specified by ifn may be used.

The result is spectral enveloping. The function size used in the
tableseg should be framesize/2, where framesize is the number of bins in
the phase vocoder analysis file that is being used by the vpvoc. Each
location in the table will be used to scale a single analysis bin. By
using different functions for ifn1, ifn2, etc.. in the tableseg, the
spectral envelope becomes a dynamically changing one. See also tableseg
and tablexseg.


===========================================================================
vrandh                                                               *vrandh*

  Description

Generates a vector of random numbers stored into a table, holding the
values for a period of time. Generates a sort of 'vectorial band-limited
noise'.

  Syntax

vrandh  ifn,  krange, kcps, ielements [, idstoffset] [, iseed] \
      [, isize] [, ioffset]

  Initialization

ifn - number of the table where the vectorial signal will be generated

ielements - number of elements of the vector

idstoffset - (optional, default=0) -- index offset for the destination
table

iseed (optional, default=0.5) -- seed value for the recursive
pseudo-random formula. A value between 0 and +1 will produce an initial
output of kamp * iseed. A negative value will cause seed
re-initialization to be skipped. A value greater than 1 will seed from
system time, this is the best option to generate a different random
sequence for each run.

isize (optional, default=0) -- if zero, a 16 bit number is generated. If
non-zero, a 31-bit random number is generated. Default is 0.

ioffset - (optional, default=0) -- a base value added to the random result.

  Performance

krange - range of random elements (from -krange to krange).

kcps - rate of generated elements in cycles per seconds.

This opcode is similar to randh, but operates on vectors instead of with
scalar values.

Though the argument isize defaults to 0, thus using a 16-bit random
number generator, using the newer 31-bit algorithm is recommended, as
this will produce a random sequence with a longer period (more random
numbers before the sequence starts repeating).

The output is a vector contained in ifn (that must be previously
allocated).

All these operators are designed to be used together with other opcodes
that operate with vector such as adsynt, etc.


===========================================================================
vrandi                                                               *vrandi*

  Description

Generate a sort of 'vectorial band-limited noise'

  Syntax

vrandi  ifn,  krange, kcps, ielements [, idstoffset] [, iseed] \
      [, isize] [, ioffset]

  Initialization

ifn - number of the table where the vectorial signal will be generated

ielements - number of elements to process

idstoffset - (optional, default=0) -- index offset for the destination
table

iseed (optional, default=0.5) -- seed value for the recursive
pseudo-random formula. A value between 0 and +1 will produce an initial
output of kamp * iseed. A negative value will cause seed
re-initialization to be skipped. A value greater than 1 will seed from
system time, this is the best option to generate a different random
sequence for each run.

isize (optional, default=0) -- if zero, a 16 bit number is generated. If
non-zero, a 31-bit random number is generated. Default is 0.

ioffset - (optional, default=0) -- a base value added to the random result.

  Performance

krange - range of random elements (from -krange to krange)

kcps - rate of generated elements in cycles per seconds

This opcode is similar to randi, but operates on vectors instead of with
scalar values.

Though argument isize defaults to 0, thus using a 16-bit random number
generator, using the newer 31-bit algorithm is recommended, as this will
produce a random sequence with a longer period (more random numbers
before the sequence starts repeating).

The output is a vector contained in ifn (that must be previously
allocated).

All these operators are designed to be used together with other opcodes
that operate with vector such as adsynt, etc.


===========================================================================
vstaudio, vstaudiog                                                *vstaudio*

  Syntax

aout1,aout2 vstaudio instance, [ain1, ain2]

aout1,aout2 vstaudiog instance, [ain1, ain2]

  Description

vstaudio and vstaudiog are used for sending and receiving audio from a
VST plugin.

vstaudio is used within an instrument definition that contains a
vstmidiout or vstnote opcode. It outputs audio for only that one
instrument. Any audio remaining in the plugin after the end of the note,
for example a reverb tail, will be cut off and should be dealt with
using a damping envelope.

vstaudiog (vstaudio global) is used in a separate instrument to process
audio from any number of VST notes or MIDI events that share the same
VST plugin instance (instance). The vstaudiog instrument must be
numbered higher than all the instruments receiving notes or MIDI data,
and the note controlling the vstplug instrument must have an indefinite
duration, or at least a duration as long as the VST plugin is active.

  Initialization

instance - the number which identifies the plugin, to be passed to other
vst4cs opcodes.

  Performance

aout1, aout2 - the audio output received from the plugin.

ain1, ain2 - the audio input sent to the plugin.


===========================================================================
vstbankload                                                     *vstbankload*

  Syntax

vstbankload instance, ipath

  Description

vstbankload is used for loading parameter banks to a VST plugin.

  Initialization

instance - the number which identifies the plugin, to be passed to other
vst4cs opcodes.

ipath - the full pathname of the parameter bank (|.fxb| file).


===========================================================================
vstedit                                                             *vstedit*

  Syntax

vstedit instance

  Description

vstedit opens the custom GUI editor window for a VST plugin. Note that
not all VST plugins have custom GUI editors. It may be necessary to use
the --displays command-line option to ensure that Csound handles events
from the editor window and displays it properly.

  Initialization

instance - the number which identifies the plugin, to be passed to other
vst4cs opcodes.


===========================================================================
vstinit                                                             *vstinit*

  Syntax

instance vstinit ilibrarypath [,iverbose]

  Description

vstinit is used to load a VST plugin into memory for use with the other
vst4cs opcodes. Both VST effects and instruments (synthesizers) can be used.

  Initialization

instance - the number which identifies the plugin, to be passed to other
vst4cs opcodes.

ilibrarypath - the full path to the vst plugin shared library (DLL, on
Windows). Remember to use '/' instead of '\' as separator.

iverbose - show plugin information and parameters when loading.


===========================================================================
vstinfo                                                             *vstinfo*

  Syntax

vstinfo instance

  Description

vstinfo displays the parameters and the programs of a VST plugin.

Note: The verbose flag in vstinit gives the same information as vstinfo.
vstinfo is useful after loading parameter banks, or when the plugin
changes parameters dynamically.

  Initialization

instance - the number which identifies the plugin, to be passed to other
vst4cs opcodes.


===========================================================================
vstmidiout                                                       *vstmidiout*

  Syntax

vstmidiout instance, kstatus, kchan, kdata1, kdata2

  Description

vstmidiout is used for sending MIDI information to a VST plugin.

  Initialization

instance - the number which identifies the plugin, to be passed to other
vst4cs opcodes.

  Performance

kstatus - the type of midi message to be sent. Currently noteon (144),
note off (128), Control Change (176), Program change (192), Aftertouch
(208) and Pitch Bend (224) are supported.

kchan - the MIDI channel transmitted on.

kdata1, kdata2 - the MIDI data pair, which varies depending on kstatus.
e.g. note/velocity for note on and note off, Controller number/value for
control change.


===========================================================================
vstnote                                                             *vstnote*

  Syntax

vstnote instance, kchan, knote, kveloc, kdur

  Description

vstnote sends a MIDI note with definite duration to a VST plugin.

  Initialization

instance - the number which identifies the plugin generated by vstinit.

  Performance

kchan - The MIDI channel to trasnmit the note on. Note that MIDI
channels are numbered starting from 0.

knote - The MIDI note number to send.

kveloc - The MIDI note's velocity.

kdur - The MIDI note's duration in seconds.

Note: Be sure the instrument containing vstnote is not finished before
the duration of the note, otherwise you'll have a 'hung' note.


===========================================================================
vstparamset,vstparamget                                         *vstparamset*

  Syntax

vstparamset instance, kparam, kvalue

kvalue vstparamget instance, kparam

  Description

vstparamset and vstparamget are used for parameter comunication to and
from a VST plugin.

  Initialization

instance - the number which identifies the plugin, to be passed to other
vst4cs opcodes.

  Performance

kparam - The number of the parameter to set or get.

kvalue - the value to set, or the the value returned by the plugin.

Parameters vary according to the plugin. To find out what parameters are
available, use the verbose option when loading the plugin with vstinit.
Note that the VST protocol specifies that all parameter values must lie
between 0.0 and 1.0, inclusive.


===========================================================================
vstprogset                                                       *vstprogset*

  Syntax

vstprogset instance, kprogram

  Description

vstprogset sets one of the programs in an |.fxb| bank.

  Initialization

instance - the number which identifies the plugin, to be passed to other
vst4cs opcodes.

kprogram - the number of the program to set.


===========================================================================
vsubv                                                                 *vsubv*

  Description

Performs subtraction between two vectorial control signals

  Syntax

vsubv  ifn1, ifn2, kelements [, kdstoffset] [, ksrcoffset] [,kverbose]

  Initialization

ifn1 - number of the table hosting the first vector to be processed

ifn2 - number of the table hosting the second vector to be processed

  Performance

kelements - number of elements of the two vectors

kdstoffset - index offset for the destination (ifn1) table (Default=0)

ksrcoffset - index offset for the source (ifn2) table (Default=0)

kverbose - Selects whether or not warnings are printed (Default=0)

vsubv subtracts two vectorial control signals, that is, each element of
ifn2 is substracted from the corresponding element of ifn1. Each
vectorial signal is hosted by a table (ifn1 and ifn2). The number of
elements contained in both vectors must be the same.

The result is a new vectorial control signal that overrides old values
of ifn1. If you want to keep the old ifn1 vector, use vcopy_i opcode to
copy it in another table. You can use kdstoffset and ksrcoffset to
specify vectors in any location of the tables.

Negative values for kdstoffset and ksrcoffset are acceptable. If
kdstoffset is negative, the out of range section of the vector will be
discarded. If ksrcoffset is negative, the out of range elements will be
assumed to be 0 (i.e. the destination elements will not be changed). If
elements for the destination vector are beyond the size of the table
(including guard point), these elements are discarded (i.e. elements do
not wrap around the tables). If elements for the source vector are
beyond the table length, these elements are taken as 0 (i.e. the
destination vector will not be changed for these elements).

If the optional kverbose argument is different to 0, the opcode will
print warning messages every k-pass if table lengths are exceeded.

  Warning

Using the same table as source and destination table in versions earlier
than 5.04, might produce unexpected behavior, so use with care.

This opcode works at k-rate (this means that every k-pass the vectors
are subtracted). There's an i-rate version of this opcode called vsubv_i.

  Note

Please note that the elements argument has changed in version 5.03 from
i-rate to k-rate. This will change the opcode's behavior in the unusual
cases where the i-rate variable ielements is changed inside the
instrument, for example in:

instr 1
ielements  =        10
           vadd     1, 1, ielements
ielements  =        20
           vadd     2, 1, ielements
           turnoff
    endin

All these operators (vaddv, vsubv, vmultv, vdivv, vpowv, vexpv, vcopy
and vmap) are designed to be used together with other opcodes that
operate with vectorial signals such as vcella, adsynt, adsynt2, etc.


===========================================================================
vsubv_i                                                             *vsubv_i*

  Description

Performs subtraction between two vectorial control signals at init time.

  Syntax

vsubv_i  ifn1, ifn2, ielements [, idstoffset] [, isrcoffset]

  Initialization

ifn1 - number of the table hosting the first vector to be processed

ifn2 - number of the table hosting the second vector to be processed

ielements - number of elements of the two vectors

idstoffset - index offset for the destination (ifn1) table (Default=0)

isrcoffset - index offset for the source (ifn2) table (Default=0)

  Performance

vsubv_i subtracts two vectorial control signals, that is, each element
of ifn2 is subrtacted from the corresponding element of ifn1. Each
vectorial signal is hosted by a table (ifn1 and ifn2). The number of
elements contained in both vectors must be the same.

The result is a new vectorial control signal that overrides old values
of ifn1. If you want to keep the old ifn1 vector, use vcopy_i opcode to
copy it in another table. You can use idstoffset and isrcoffset to
specify vectors in any location of the tables.

Negative values for idstoffset and isrcoffset are acceptable. If
idstoffset is negative, the out of range section of the vector will be
discarded. If isrcoffset is negative, the out of range elements will be
assumed to be 0 (i.e. the destination elements will not be changed). If
elements for the destination vector are beyond the size of the table
(including guard point), these elements are discarded (i.e. elements do
not wrap around the tables). If elements for the source vector are
beyond the table length, these elements are taken as 0 (i.e. the
destination vector will not be changed for these elements).

  Warning

Using the same table as source and destination table in versions earlier
than 5.04, might produce unexpected behavior, so use with care.

This opcode works at init time. There's an k-rate version of this opcode
called vsubv.

All these operators (vaddv_i,vsubv_i,vmultv_i,vdivv_i,vpowv_i,vexpv_i,
vcopy and vmap) are designed to be used together with other opcodes that
operate with vectorial signals such as vcella, adsynt, adsynt2 etc.


===========================================================================
vtable1k                                                           *vtable1k*

  Description

This opcode reads vectors from tables at k-rate.

  Syntax

vtable1k  kfn,kout1 [, kout2, kout3, .... , koutN ]

  Performance

kfn - table number

kout1...koutN - output vector elements

vtable1k is a reduced version of vtablek, it only allows to access the
first vector (it is equivalent to vtablek with kndx = zero, but a bit
faster). It is useful to easily and quickly convert a set of values
stored in a table into a set of k-rate variables to be used in normal
opocodes, instead of using individual table opcodes for each value.

  Note

vtable1k is an unusual opcode as it produces its output on the right
side arguments of the opcode.


===========================================================================
vtablei                                                             *vtablei*

  Description

This opcode reads vectors from tables.

  Syntax

vtablei  indx, ifn, interp, ixmode, iout1 [, iout2, iout3, .... , ioutN ]

  Initialization

indx - Index into f-table, either a positive number range matching the
table length (ixmode = 0) or a 0 to 1 range (ixmode != 0).

ifn - table number

iout1...ioutN - output vector elements

ixmode - index data mode. The default value is 0.

== 0 index is treated as a raw table location,

== 1 index is normalized (0 to 1).

interp - vtable (vector table) family of opcodes allows the user to
switch beetween interpolated or non-interpolated output by means of the
interp argument.

  Performance

This opcode is useful in all cases in which one needs to access sets of
values associated to unique indexes (for example, multi-channel samples,
STFT bin frames, spectral formants, p-field based scores etc.). The
number of elements of each vector (length of the vector) is determined
by the number of optional arguments on the right (iout1 , iout2, iout3,
.... ioutN).

vtable (vector table) family of opcodes allows the user to switch
beetween interpolated or non-interpolated output by means of the interp
argument.

Notice that no wrap nor limit mode is implemented. So, if an index
attempt to access to a zone not allocated by the table, Csound will
probably crash. However this drawback can be easily avoided by using
wrap or limit opcodes applied to indexes before using vtable, in order
to correct eventual out-of-range values.

  Note

Notice that vtablei's output arguments are placed at the right of the
opcode name, differently from usual (this style is already used in other
opcodes using undefined lists of output arguments such as fin or trigseq).


===========================================================================
vtablek                                                             *vtablek*

  Description

This opcode reads vectors from tables at k-rate.

  Syntax

vtablek  kndx, kfn, kinterp, ixmode, kout1 [, kout2, kout3, .... , koutN ]

  Initialization

ixmode - index data mode. The default value is 0.

== 0 index is treated as a raw table location,

== 1 index is normalized (0 to 1).

kinterp - switch beetween interpolated or non-interpolated output. 0 ->
non-interpolation , non-zero -> interpolation activated

  Performance

kndx - Index into f-table, either a positive number range matching the
table length (ixmode = 0) or a 0 to 1 range (ixmode != 0).

kfn - table number

kout1...koutN - output vector elements

This opcode is useful in all cases in which one needs to access sets of
values associated to unique indexes (for example, multi-channel samples,
STFT bin frames, spectral formants, p-field based scores etc.). The
number of elements of each vector (length of the vector) is determined
by the number of optional arguments on the right (kout1 , kout2, kout3,
.... koutN).

vtablek allows the user to switch beetween interpolated or
non-interpolated output at k-rate by means of kinterp argument.

vtablek allows also to switch the table number at k-rate (but this is
possible only when vector frames of each used table have the same number
of elements, otherwise unpredictable results could occurr), as well as
to choose indexing style (raw or normalized, see also ixmode argument of
table opcode ).

Notice that no wrap nor limit mode is implemented. So, if an index
attempt to access to a zone not allocated by the table, Csound will
probably crash. However this drawback can be easily avoided by using
wrap or limit opcodes applied to indexes before using vtable, in order
to correct eventual out-of-range values.

  Note

Notice that vtablek's output arguments are placed at the left of the
opcode name, differently from usual (this style is already used in other
opcodes using undefined lists of output arguments such as fin or trigseq).


===========================================================================
vtablea                                                             *vtablea*

  Description

This opcode reads vectors from tables at a-rate.

  Syntax

vtablea  andx, kfn, kinterp, ixmode, aout1 [, aout2, aout3, .... , aoutN ]

  Initialization

ixmode - index data mode. The default value is 0.

== 0 index is treated as a raw table location,

== 1 index is normalized (0 to 1).

  Performance

andx - Index into f-table, either a positive number range matching the
table length (ixmode = 0) or a 0 to 1 range (ixmode != 0).

kfn - table number

kinterp - switch beetween interpolated or non-interpolated output. 0 ->
non-interpolation , non-zero -> interpolation activated

aout1...aoutN - output vector elements

This opcode is useful in all cases in which one needs to access sets of
values associated to unique indexes (for example, multi-channel samples,
STFT bin frames, spectral formants, p-field based scores etc.). The
number of elements of each vector (length of the vector) is determined
by the number of optional arguments on the right (aout1 , aout2, aout3,
.... aoutN).

vtablea allows the user to switch beetween interpolated or
non-interpolated output at k-rate by means of kinterp argument.

vtablea allows also to switch the table number at k-rate (but this is
possible only when vector frames of each used table have the same number
of elements, otherwise unpredictable results could occurr), as well as
to choose indexing style (raw or normalized, see also ixmode argument of
table opcode ).

Notice that no wrap nor limit mode is implemented. So, if an index
attempt to access to a zone not allocated by the table, Csound will
probably crash. However this drawback can be easily avoided by using
wrap or limit opcodes applied to indexes before using vtablea, in order
to correct eventual out-of-range values.

  Note

Notice that vtablea's output arguments are placed at the right of the
opcode name, differently from usual (this style is already used in other
opcodes using undefined lists of output arguments such as fin or trigseq).


===========================================================================
vtablewi                                                           *vtablewi*

  Description

This opcode writes vectors to tables at init time.

  Syntax

vtablewi  indx, ifn, ixmode, inarg1 [, inarg2, inarg3 , .... , inargN ]

  Initialization

indx - Index into f-table, either a positive number range matching the
table length (ixmode = 0) or a 0 to 1 range (ixmode != 0).

ifn - table number

ixmode - index data mode. The default value is 0.

== 0 index is treated as a raw table location,

== 1 index is normalized (0 to 1).

inarg1...inargN - input vector elements

  Performance

This opcode is useful in all cases in which one needs to write sets of
values associated to unique indexes (for example, multi-channel samples,
STFT bin frames, spectral formants, p-field based scores etc.). The
number of elements of each vector (length of the vector) is determined
by the number of optional arguments on the right (inarg1, inarg2,
inarg3, .... inargN).

Notice that no wrap nor limit mode is implemented. So, if an index
attempt to access to a zone not allocated by the table, Csound will
probably crash. However this drawback can be easily avoided by using
wrap or limit opcodes applied to indexes before using vtablewi, in order
to correct eventual out-of-range values.


===========================================================================
vtablewk                                                           *vtablewk*

  Description

This opcode writes vectors to tables at k-rate.

  Syntax

vtablewk  kndx, kfn, ixmode, kinarg1 [, kinarg2, kinarg3 , .... , kinargN ]

  Initialization

ixmode - index data mode. The default value is 0.

== 0 index is treated as a raw table location,

== 1 index is normalized (0 to 1).

  Performance

kndx - Index into f-table, either a positive number range matching the
table length (ixmode = 0) or a 0 to 1 range (ixmode != 0).

kfn - table number

kinarg1...kinargN - input vector elements

This opcode is useful in all cases in which one needs to write sets of
values associated to unique indexes (for example, multi-channel samples,
STFT bin frames, spectral formants, p-field based scores etc.). The
number of elements of each vector (length of the vector) is determined
by the number of optional arguments on the right (kinarg1, kinarg2,
kinarg3, .... kinargN).

vtablewk allows also to switch the table number at k-rate (but this is
possible only when vector frames of each used table have the same number
of elements, otherwise unpredictable results could occurr), as well as
to choose indexing style (raw or normalized, see also ixmode argument of
table opcode ).

Notice that no wrap nor limit mode is implemented. So, if an index
attempt to access to a zone not allocated by the table, Csound will
probably crash. However this drawback can be easily avoided by using
wrap or limit opcodes applied to indexes before using vtablewk, in order
to correct eventual out-of-range values.


===========================================================================
vtablewa                                                           *vtablewa*

  Description

This opcode writes vectors to tables at a-rate.

  Syntax

vtablewa  andx, kfn, ixmode, ainarg1 [, ainarg2, ainarg3 , .... , ainargN ]

  Initialization

ixmode - index data mode. The default value is 0.

== 0 index is treated as a raw table location,

== 1 index is normalized (0 to 1).

  Performance

andx - Index into f-table, either a positive number range matching the
table length (ixmode = 0) or a 0 to 1 range (ixmode != 0).

kfn - table number

ainarg1...ainargN - input vector elements

This opcode is useful in all cases in which one needs to write sets of
values associated to unique indexes (for example, multi-channel samples,
STFT bin frames, spectral formants, p-field based scores etc.). The
number of elements of each vector (length of the vector) is determined
by the number of optional arguments on the right (ainarg1 , ainarg2,
ainarg3, .... ainargN).

vtablewa allows also to switch the table number at k-rate (but this is
possible only when vector frames of each used table have the same number
of elements, otherwise unpredictable results could occurr), as well as
to choose indexing style (raw or normalized, see also ixmode argument of
table opcode ).

Notice that no wrap nor limit mode is implemented. So, if an index
attempt to access to a zone not allocated by the table, Csound will
probably crash. However this drawback can be easily avoided by using
wrap or limit opcodes applied to indexes before using vtablewa, in order
to correct eventual out-of-range values.


===========================================================================
vtabi                                                                 *vtabi*

  Description

This opcode reads vectors from tables.

  Syntax

vtabi  indx, ifn, iout1 [, iout2, iout3, .... , ioutN ]

  Initialization

indx - Index into f-table, either a positive number range matching the
table length

ifn - table number

iout1...ioutN - output vector elements

  Performance

This opcode is useful in all cases in which one needs to access sets of
values associated to unique indexes (for example, multi-channel samples,
STFT bin frames, spectral formants, p-field based scores etc.). The
number of elements of each vector (length of the vector) is determined
by the number of optional arguments on the right (iout1, iout2, iout3,
.... ioutN).

Notice that no wrap nor limit mode is implemented. So, if an index
attempt to access to a zone not allocated by the table, Csound will
probably crash. However this drawback can be easily avoided by using
wrap or limit opcodes applied to indexes before using vtabi, in order to
correct eventual out-of-range values.

The vtab family is similar to vtable, but is much faster because
interpolation is not available, table number cannot be changed after
initialization, and only raw indexing is supported.

  Note

Notice that vtabi's output arguments are placed at the right of the
opcode name, differently from usual (this style is already used in other
opcodes using undefined lists of output arguments such as fin or trigseq).


===========================================================================
vtabk                                                                 *vtabk*

  Description

This opcode reads vectors from tables at k-rate.

  Syntax

vtabk  kndx, ifn, kout1 [, kout2, kout3, .... , koutN ]

  Initialization

ifn - table number

  Performance

kndx - Index into f-table, either a positive number range matching the
table length

kout1...koutN - output vector elements

This opcode is useful in all cases in which one needs to access sets of
values associated to unique indexes (for example, multi-channel samples,
STFT bin frames, spectral formants, p-field based scores etc.) . The
number of elements of each vector (length of the vector) is determined
by the number of optional arguments on the right (kout1, kout2, kout3,
.... koutN).

Notice that no wrap nor limit mode is implemented. So, if an index
attempt to access to a zone not allocated by the table, Csound will
probably crash. However this drawback can be easily avoided by using
wrap or limit opcodes applied to indexes before using vtabk, in order to
correct eventual out-of-range values.

The vtab family is similar to vtable, but is much faster because
interpolation is not available, table number cannot be changed after
initialization, and only raw indexing is supported.

  Note

Notice that vtabk's output arguments are placed at the right of the
opcode name, differently from usual (this style is already used in other
opcodes using undefined lists of output arguments such as fin or trigseq).


===========================================================================
vtaba                                                                 *vtaba*

  Description

This opcode reads vectors from tables at a-rate.

  Syntax

vtaba  andx, ifn, aout1 [, aout2, aout3, .... , aoutN ]

  Initialization

ifn - table number

  Performance

andx - Index into f-table, either a positive number range matching the
table length

aout1...aoutN - output vector elements

This opcode is useful in all cases in which one needs to access sets of
values associated to unique indexes (for example, multi-channel samples,
STFT bin frames, spectral formants, p-field based scores etc.). The
number of elements of each vector (length of the vector) is determined
by the number of optional arguments on the right (aout1, aout2, aout3,
.... aoutN).

Notice that no wrap nor limit mode is implemented. So, if an index
attempt to access to a zone not allocated by the table, Csound will
probably crash. However this drawback can be easily avoided by using
wrap or limit opcodes applied to indexes before using vtaba, in order to
correct eventual out-of-range values.

The vtab family is similar to the vtable family, but is much faster
because interpolation is not available, table number cannot be changed
after initialization, and only raw indexing is supported.

  Note

Notice that vtaba's output arguments are placed at the right of the
opcode name, differently from usual (this style is already used in other
opcodes using undefined lists of output arguments such as fin or trigseq).


===========================================================================
vtabwi                                                               *vtabwi*

  Description

This opcode writes vectors to tables at init time.

  Syntax

vtabwi  indx, ifn, inarg1 [, inarg2, inarg3 , .... , inargN ]

  Initialization

indx - Index into f-table, a positive number range matching the table
length

ifn - table number

inarg1...inargN - input vector elements

  Performance

This opcode is useful in all cases in which one needs to write sets of
values associated to unique indexes (for example, multi-channel samples,
STFT bin frames, spectral formants, p-field based scores etc.). The
number of elements of each vector (length of the vector) is determined
by the number of optional arguments on the right (inarg1, inarg2,
inarg3, .... inargN).

Notice that no wrap nor limit mode is implemented. So, if an index
attempt to access to a zone not allocated by the table, Csound will
probably crash. However this drawback can be easily avoided by using
wrap or limit opcodes applied to indexes before using vtabwi, in order
to correct eventual out-of-range values.


===========================================================================
vtabwk                                                               *vtabwk*

  Description

This opcode writes vectors to tables at k-rate.

  Syntax

vtabwk  kndx, ifn, kinarg1 [, kinarg2, kinarg3 , .... , kinargN ]

  Initialization

ifn - table number

  Performance

kndx - Index into f-table, a positive number range matching the table
length

kinarg1...kinargN - input vector elements

This opcode is useful in all cases in which one needs to write sets of
values associated to unique indexes (for example, multi-channel samples,
STFT bin frames, spectral formants, p-field based scores etc.) . The
number of elements of each vector (length of the vector) is determined
by the number of optional arguments on the right (kinarg1, kinarg2,
kinarg3, .... kinargN).

Notice that no wrap nor limit mode is implemented. So, if an index
attempt to access to a zone not allocated by the table, Csound will
probably crash. However this drawback can be easily avoided by using
wrap or limit opcodes applied to indexes before using vtabwk, in order
to correct eventual out-of-range values.


===========================================================================
vtabwa                                                               *vtabwa*

  Description

This opcode writes vectors to tables at a-rate.

  Syntax

vtabwa  andx, ifn, ainarg1 [, ainarg2, ainarg3 , .... , ainargN ]

  Initialization

ifn - table number

  Performance

andx - Index into f-table, a positive number range matching the table
length

ainarg1...ainargN - input vector elements

This opcode is useful in all cases in which one needs to write sets of
values associated to unique indexes (for example, multi-channel samples,
STFT bin frames, spectral formants, p-field based scores etc.). The
number of elements of each vector (length of the vector) is determined
by the number of optional arguments on the right (ainarg1, ainarg2,
ainarg3, .... ainargN).

Notice that no wrap nor limit mode is implemented. So, if an index
attempt to access to a zone not allocated by the table, Csound will
probably crash. However this drawback can be easily avoided by using
wrap or limit opcodes applied to indexes before using vtabwa, in order
to correct eventual out-of-range values.


===========================================================================
vwrap                                                                 *vwrap*

  Description

Wraps elements of vectorial control signals.

  Syntax

vwrap  ifn, kmin, kmax, ielements

  Initialization

ifn - number of the table hosting the vector to be processed

ielements - number of elements of the vector

  Performance

kmin - minimum threshold value

kmax - maximum threshold value

vwrap wraps around each element of corresponding vector if it exceeds
low or high thresholds.

These opcodes are similar to limit, wrap and mirror, but operate with a
vectorial signal instead of with a scalar signal.

Result overrides old values of ifn1, if these are out of min/max
interval. If you want to keep input vector, use vcopy opcode to copy it
in another table.

All these opcodes are designed to be used together with other opcodes
that operate with vectorial signals such as vcella, adsynt, adsynt2 etc.


===========================================================================
waveset                                                             *waveset*

  Description

A simple time stretch by repeating cycles.

  Syntax

ares waveset ain, krep [, ilen]

  Initialization

ilen (optional, default=0) -- the length (in samples) of the audio
signal. If ilen is set to 0, it defaults to half the given note length
(p3).

  Performance

ain -- the input audio signal.

krep -- the number of times the cycle is repeated.

The input is read and each complete cycle (two zero-crossings) is
repeated krep times.

There is an internal buffer as the output is clearly slower that the
input. Some care is taken if the buffer is too short, but there may be
strange effects.


===========================================================================
websocket                                                         *websocket*

  Description

websocket reads and writes N signals and arrays using a websocket
connection.

  Syntax

xout1[, xout2, xout3, ..., xoutN] websocket iport, xin1[, xin2, xin3, ..., xinN]

  Initialization

iport the local web port to read/write data.

  Performance

xout1,... xoutN -- The output variables which contain data received from
a websocket. On the web side the websocket must send data using a
protocol name that matches the output variable name e.g. "ksignal" for a
k-rate variable. If an array is intended to be received from a websocket
it must be first initialised before being used as an output to the
opcode. Otherwise the opcode doesn't know what size data to expect from
the websocket. When sending data to a websocket from the web page it
must be sent as a 32 or 64 bit array, depending on the build of Csound
that is being used.

xin1,... xinN -- The input variables which contain data which is sent to
a websocket. On the web side the websocket receives data using a
protocol name that matches the input variable name e.g. "ksignal" for a
k-rate variable. When receiving data from a websocket on the web page it
must be read as a 32 or 64 bit array, depending on the build of Csound
that is being used.

  Note
The total number of input and output arguments is limited to 20.

A-rate variables must be send and received as arrays that are ksmps
samples large. A-rate arrays similarly are sent and received as ksmps by
the number of elements in the array. K-rate variables are sent and
received as a single element array. K-rate arrays are sent and received
as arrays with matching numbers of elements.


===========================================================================
weibull                                                             *weibull*

  Description

Weibull distribution random number generator (positive values only).
This is an x-class noise generator

  Syntax

ares weibull ksigma, ktau

ires weibull ksigma, ktau

kres weibull ksigma, ktau

  Performance

ksigma -- scales the spread of the distribution.

ktau -- if greater than one, numbers near ksigma are favored. If smaller
than one, small values are favored. If t equals 1, the distribution is
exponential. Outputs only positive numbers.

For more detailed explanation of these distributions, see:

 1. C. Dodge - T.A. Jerse 1985. Computer music. Schirmer books. pp.265 - 286

 2. D. Lorrain. A panoply of stochastic cannons. In C. Roads, ed. 1989.
    Music machine . Cambridge, Massachusetts: MIT press, pp. 351 - 379.


===========================================================================
wgbow                                                                 *wgbow*

  Description

Audio output is a tone similar to a bowed string, using a physical model
developed from Perry Cook, but re-coded for Csound.

  Syntax

ares wgbow kamp, kfreq, kpres, krat, kvibf, kvamp \
    [, ifn] [, iminfreq]

  Initialization

ifn -- optional table of shape of vibrato, defaults to a sine table.

iminfreq (optional) -- lowest frequency at which the instrument will
play. If it is omitted it is taken to be the same as the initial kfreq.
If iminfreq is negative, initialization will be skipped.

  Performance

A note is played on a string-like instrument, with the arguments as below.

kamp -- amplitude of note.

kfreq -- frequency of note played.

kpres -- a parameter controlling the pressure of the bow on the string.
Values should be about 3. The useful range is approximately 1 to 5.

krat -- the position of the bow along the string. Usual playing is about
0.127236. The suggested range is 0.025 to 0.23.

kvibf -- frequency of vibrato in Hertz. Suggested range is 0 to 12

kvamp -- amplitude of the vibrato


===========================================================================
wgbowedbar                                                       *wgbowedbar*

  Description

A physical model of a bowed bar, belonging to the Perry Cook family of
waveguide instruments.

  Syntax

ares wgbowedbar kamp, kfreq, kpos, kbowpres, kgain [, iconst] [, itvel] \
      [, ibowpos] [, ilow]

  Initialization

iconst (optional, default=0) -- an integration constant. Default is zero.

itvel (optional, default=0) -- either 0 or 1. When itvel = 0, the bow
velocity follows an ADSR style trajectory. When itvel = 1, the value of
the bow velocity decays in an exponentially.

ibowpos (optional, default=0) -- the position on the bow, which affects
the bow velocity trajectory.

ilow (optional, default=0) -- lowest frequency required

  Performance

kamp -- amplitude of signal

kfreq -- frequency of signal

kpos -- position of the bow on the bar, in the range 0 to 1

kbowpres -- pressure of the bow (as in wgbowed)

kgain -- gain of filter. A value of about 0.809 is suggested.


===========================================================================
wgbrass                                                             *wgbrass*

  Description

Audio output is a tone related to a brass instrument, using a physical
model developed from Perry Cook, but re-coded for Csound.

  Syntax

ares wgbrass kamp, kfreq, ktens, iatt, kvibf, kvamp \
    [, ifn] [, iminfreq]

  Initialization

iatt -- time taken to reach full pressure

ifn -- optional table of shape of vibrato, defaults to a sine table.

iminfreq -- lowest frequency at which the instrument will play. If it is
omitted it is taken to be the same as the initial kfreq. If iminfreq is
negative, initialization will be skipped.

  Performance

A note is played on a brass-like instrument, with the arguments as below.

kamp -- Amplitude of note.

kfreq -- Frequency of note played.

ktens -- lip tension of the player. Suggested value is about 0.4

kvibf -- frequency of vibrato in Hertz. Suggested range is 0 to 12

kvamp -- amplitude of the vibrato

  NOTE

This is rather poor, and at present uncontrolled. Needs revision, and
possibly more parameters.


===========================================================================
wgclar                                                               *wgclar*

  Description

Audio output is a tone similar to a clarinet, using a physical model
developed from Perry Cook, but re-coded for Csound.

  Syntax

ares wgclar kamp, kfreq, kstiff, \
    iatt, idetk, kngain, kvibf, kvamp [, ifn] [, iminfreq]

  Initialization

iatt -- time in seconds to reach full blowing pressure. 0.1 seems to
correspond to reasonable playing. A longer time gives a definite initial
wind sound.

idetk -- time in seconds taken to stop blowing. 0.1 is a smooth ending

ifn (optional) -- table of shape of vibrato, defaults yo te usual sine
table.

iminfreq (optional) -- lowest frequency at which the instrument will
play. If it is omitted it is taken to be the same as the initial kfreq.
If iminfreq is negative, initialization will be skipped.

  Performance

A note is played on a clarinet-like instrument, with the arguments as
below.

kamp -- Amplitude of note.

kfreq -- Frequency of note played.

kstiff -- a stiffness parameter for the reed. Values should be negative,
and about -0.3. The useful range is approximately -0.44 to -0.18.

kngain -- amplitude of the noise component, about 0 to 0.5

kvibf -- frequency of vibrato in Hertz. Suggested range is 0 to 12

kvamp -- amplitude of the vibrato


===========================================================================
wgflute                                                             *wgflute*

  Description

Audio output is a tone similar to a flute, using a physical model
developed from Perry Cook, but re-coded for Csound.

  Syntax

ares wgflute kamp, kfreq, kjet, iatt,
    idetk, kngain, kvibf, kvamp [, ifn] [, iminfreq] [, ijetrf] [, iendrf]

  Initialization

iatt -- time in seconds to reach full blowing pressure. 0.1 seems to
correspond to reasonable playing.

idetk -- time in seconds taken to stop blowing. 0.1 is a smooth ending

ifn (optional) -- table of shape of vibrato, defaults to the usual sine
table.

iminfreq (optional) -- lowest frequency at which the instrument will
play. If it is omitted it is taken to be the same as the initial kfreq.
If iminfreq is negative, initialization will be skipped.

ijetrf (optional, default=0.5) -- amount of reflection in the breath jet
that powers the flute. Default value is 0.5.

iendrf (optional, default=0.5) -- reflection coefficient of the breath
jet. Default value is 0.5. Both ijetrf and iendrf are used in the
calculation of the pressure differential.

  Performance

kamp -- Amplitude of note.

kfreq -- Frequency of note played. While it can be varied in
performance, I have not tried it.

kjet -- a parameter controlling the air jet. Values should be positive,
and about 0.3. The useful range is approximately 0.08 to 0.56.

kngain -- amplitude of the noise component, about 0 to 0.5

kvibf -- frequency of vibrato in Hertz. Suggested range is 0 to 12

kvamp -- amplitude of the vibrato


===========================================================================
wgpluck                                                             *wgpluck*

  Description

A high fidelity simulation of a plucked string, using interpolating
delay-lines.

  Syntax

ares wgpluck icps, iamp, kpick, iplk, idamp, ifilt, axcite

  Initialization

icps -- frequency of plucked string

iamp -- amplitude of string pluck

iplk -- point along the string, where it is plucked, in the range of 0
to 1. 0 = no pluck

idamp -- damping of the note. This controls the overall decay of the
string. The greater the value of idamp, the faster the decay. Negative
values will cause an increase in output over time.

ifilt -- control the attenuation of the filter at the bridge. Higher
values cause the higher harmonics to decay faster.

  Performance

kpick -- proportion of the way along the point to sample the output.

axcite -- a signal which excites the string.

A string of frequency icps is plucked with amplitude iamp at point iplk.
The decay of the virtual string is controlled by idamp and ifilt which
simulate the bridge. The oscillation is sampled at the point kpick, and
excited by the signal axcite.


===========================================================================
wgpluck2                                                           *wgpluck2*

  Description

wgpluck2 is an implementation of the physical model of the plucked
string, with control over the pluck point, the pickup point and the
filter. Based on the Karplus-Strong algorithm.

  Syntax

ares wgpluck2 iplk, kamp, icps, kpick, krefl

  Initialization

iplk -- The point of pluck is iplk, which is a fraction of the way up
the string (0 to 1). A pluck point of zero means no initial pluck.

icps -- The string plays at icps pitch.

  Performance

kamp -- Amplitude of note.

kpick -- Proportion of the way along the string to sample the output.

krefl -- the coefficient of reflection, indicating the lossiness and the
rate of decay. It must be strictly between 0 and 1 (it will complain
about both 0 and 1).


===========================================================================
wguide1                                                             *wguide1*

  Description

A simple waveguide model consisting of one delay-line and one
first-order lowpass filter.

  Syntax

ares wguide1 asig, xfreq, kcutoff, kfeedback

  Performance

asig -- the input of excitation noise.

xfreq -- the frequency (i.e. the inverse of delay time) Changed to
x-rate in Csound version 3.59.

kcutoff -- the filter cutoff frequency in Hz.

kfeedback -- the feedback factor.

wguide1 is the most elemental waveguide model, consisting of one
delay-line and one first-order lowpass filter.

Implementing waveguide algorithms as opcodes, instead of orc
instruments, allows the user to set kr different than sr, allowing
better performance particulary when using real-time.

wguide1.

wguide1.


===========================================================================
wguide2                                                             *wguide2*

  Description

A model of beaten plate consisting of two parallel delay-lines and two
first-order lowpass filters.

  Syntax

ares wguide2 asig, xfreq1, xfreq2, kcutoff1, kcutoff2, \
      kfeedback1, kfeedback2

  Performance

asig -- the input of excitation noise

xfreq1, xfreq2 -- the frequency (i.e. the inverse of delay time) Changed
to x-rate in Csound version 3.59.

kcutoff1, kcutoff2 -- the filter cutoff frequency in Hz.

kfeedback1, kfeedback2 -- the feedback factor

wguide2 is a model of beaten plate consisting of two parallel
delay-lines and two first-order lowpass filters. The two feedback lines
are mixed and sent to the delay again each cycle.

Implementing waveguide algorithms as opcodes, instead of orc
instruments, allows the user to set kr different than sr, allowing
better performance particulary when using real-time.

wguide2.

wguide2.

  Note

As a rule of thumb, to avoid making wguide2 unstable, the sum of the two
feedback values should be below 0.5.


===========================================================================
while                                                                 *while*

  Description

A syntactic looping construction.

  Syntax

while  condition do
    ... od

  Performance

The statements between the do and od form the body of a loop which is
obeyed while the conditional remains true.


===========================================================================
wiiconnect                                                       *wiiconnect*

  Description

Opens and at control-rate polls up to four external Nintendo Wiimote
controllers.

  Syntax

ires wiiconnect [itimeout, imaxnum]

  Initialization

itimeout -- integer number of seconds the system should wait for all
Wiimotes to be connected. If not given it defaults to 10 seconds.

imaxnum -- maximum number of Wiimotes to locate. If not given it
defaults to 4.

Initially each Wiimote has its numeric allocation indicated by lighting
one of the four LEDs.

ires -- return value is 1 if sucess or zero on failure.

  Performance

  Note

Please note that these opcodes are currently only supported on Linux.

Every control cycle each Wiimote is polled for its status and position.
These values are read by the wiidata opcode. The result returned is 1 in
most cases, but will be zero if a Wiimote disconnects,


===========================================================================
wiidata                                                             *wiidata*

  Description

Reads data fields from upto four external Nintendo Wiimote controllers.

  Syntax

kres wiidata kcontrol[, knum]

  Initialization

This opcode must be used in conjuction with a running wiiconnect opcode.

  Performance

  Note

Please note that these opcodes are currently only supported on Linux.

kcontrol -- the code for which control to read

knum -- the number of the which Wiimote to access, which defaults to the
first one.

On each access a particular data item of the Wiimote is read. The
currently implemented controls are given below, together with the macro
name defined in the file wii_mac:

0 (WII_BUTTONS): returns a bit pattern for all buttons that were pressed.

1 (WII_TWO): returns 1 if the button has just been pressed, or 0 otherwise.

2 (WII_ONE): as above.

3 (WII_B): as above.

4 (WII_A): as above.

5 (WII_MINUS): as above.

8 (WII_HOME): as above.

9 (WII_LEFT): as above.

10 (WII_RIGHT): as above.

11 (WII_DOWN): as above.

12 (WII_UP): as above.

13 (WII_PLUS): as above.

If the control number is 100 more than one of these button codes then
the current state of the button is returned. Macros with names like
WII_S_TWO etc are defined for this.

If the control number is 200 more than one of these button codes then
the return value is 1 if the button i held and 0 otherwise. Macros with
names like WII_H_TWO etc are defined for this.

If the control number is 300 more than one of these button codes then
the value is 1 if the button has just been released, and 0 otherwise.
Macros with names like WII_R_TWO etc are defined for this.

20 (WII_PITCH): The pitch of the Wiimote. The value is in degrees
between -90 and +90, unless modified by a wiirange call.

21 (WII_ROLL): The roll of the Wiimote. The value is in degrees between
-90 and +90, unless modified by a wiirange call.

23 (WII_FORCE_X): The force applied to the Wiimote in the three axes.

24 (WII_FORCE_Y):

25 (WII_FORCE_Z):

26 (WII_FORCE_TOTAL): The total magnitude of the force applied to the
Wiimote.

27 (WII_BATTERY): The percent of the battery that remains.

28 (WII_NUNCHUK_ANG): The angle of the nunchuk joystick in degrees.

29 (WII_NUNCHUK_MAG): The magnitude of the nunchuk joystick from neutral.

30 (WII_NUNCHUK_PITCH): The pitch of the nunchuk in degrees, in range
-90 to +90 unless modified by a wiirange call.

31 (WII_NUNCHUK_ROLL): The roll of the nunchuk in degrees, in range -90
to +90 unless modified by a wiirange call.

33 (WII_NUNCHUK_Z): The state of the nunchuk Z button.

34 (WII_NUNCHUK_C): The state of the nunchuk C button.

35 (WII_IR1_X): The infrared pointing of the Wiimote.

36 (WII_IR1_Y):

37 (WII_IR1_Z):


===========================================================================
wiirange                                                           *wiirange*

  Description

Sets scaling and range limits for certain Wiimote fields.

  Syntax

 wiirange icontrol, iminimum, imaximum[, inum]

  Initialization

This opcode must be used in conjuction with a running wiiconnect opcode.

icontrol -- which control is to be scaled. This must be one of 20
(WII_PITCH), 21 (WII_ROLL), 30 (WII_NUNCHUK_PITCH), 31 (WII_NUNCHUK_ROLL).

iminimum -- minimun value for control.

imaximum -- maximum value for control.

  Note

Please note that these opcodes are currently only supported on Linux.


===========================================================================
wiisend                                                             *wiisend*

  Description

Sends data to one of a number of external Nintendo Wiimote controllers.

  Syntax

kres wiisend kcontrol, kvalue[, knum]

  Initialization

This opcode must be used in conjuction with a running wiiconnect opcode.

  Performance

  Note

Please note that these opcodes are currently only supported on Linux.

kcontrol -- the code for which control to write.

kvalue -- the value to write to the control.

knum -- the number of the which Wiimote to access, which defaults to the
first one (zero).

On each access a particular data item of the Wiimote is written. The
currently implemented controls are given below, together with the macro
name defined in the file wii_mac:

3 (WII_RUMBLE): starts or stops the Wiimote rumbling, depending on the
value of kvalue (0 to stop, 1 to start).

4 (WII_SET_LEDS): set the four LED lights on the Wiimote to the binary
representation of kvalue.


===========================================================================
window                                                               *window*

  Description

Applies a given window shape to a vector stored in an array. The output
is an array with the windowed vector.

  Initialization

itype -- optional window type: 0 = Hamming, 1 = Hanning (von Hann)
(defaults to 1).

  Syntax

u

kout[] window kin[][, koff, itype]

  Performance

kout[] -- output array containing the windowed output. It will be
created if it does not exist.

kin[] -- input array containing the input vector.

koff -- offset to make window start at position koff (non-negative only,
defaults to 0).


===========================================================================
wrap                                                                   *wrap*

  Description

Wraps-around the signal that exceeds the low and high thresholds.

  Syntax

ares wrap asig, klow, khigh

ires wrap isig, ilow, ihigh

kres wrap ksig, klow, khigh

  Initialization

isig -- input signal

ilow -- low threshold

ihigh -- high threshold

  Performance

xsig -- input signal

klow -- low threshold

khigh -- high threshold

wrap wraps-around the signal that exceeds the low and high thresholds.

This opcode is useful in several situations, such as table indexing or
for clipping and modeling a-rate, i-rate or k-rate signals. wrap is also
useful for wrap-around of table data when the maximum index is not a
power of two (see table and tablei). Another use of wrap is in cyclical
event repeating, with arbitrary cycle length.


===========================================================================
writescratch                                                   *writescratch*

  Description

The writescratch opcode writes one of four scalar values to be stored in
the instance of an instrument.

  Syntax

writescratchival[, index]

  Initialisation

ival -- variable to write.

index -- which value to write, defaulting to zero.


===========================================================================
wterrain                                                           *wterrain*

  Description

A simple wave-terrain synthesis opcode.

  Syntax

aout wterrain kamp, kpch, k_xcenter, k_ycenter, k_xradius, k_yradius, \
      itabx, itaby

  Initialization

itabx, itaby -- The two tables that define the terrain.

  Performance

The output is the result of drawing an ellipse with axes k_xradius and
k_yradius centered at (k_xcenter, k_ycenter), and traversing it at
frequency kpch.


===========================================================================
xadsr                                                                 *xadsr*

  Description

Calculates the classical ADSR envelope

  Syntax

ares xadsr iatt, idec, islev, irel [, idel]

kres xadsr iatt, idec, islev, irel [, idel]

  Initialization

iatt -- duration of attack phase

idec -- duration of decay

islev -- level for sustain phase

irel -- duration of release phase

idel -- period of zero before the envelope starts

  Performance

The envelope generated is the range 0 to 1 and may need to be scaled
further, depending on the amplitude required. If using 0dbfs = 1,
scaling down will probably be required since playing more than one note
might result in clipping. If not using 0dbfs, scaling to a large
amplitude (e.g. 32000) might be required.

The envelope may be described as:

Picture of an ADSR envelope.

Picture of an ADSR envelope.

The length of the sustain is calculated from the length of the note.
This means xadsr is not suitable for use with MIDI events, use mxadsr
instead. The opcode xadsr is identical to adsr except it uses
exponential, rather than linear, line segments.


===========================================================================
xin                                                                     *xin*

  Description

The xin and xout opcodes copy variables to and from the opcode
definition, allowing communication with the calling instrument.

The types of input and output variables are defined by the parameters
intypes and outtypes.

  Notes

  * xin and xout should be called only once, and xin should precede
    xout, otherwise an init error and deactivation of the current
    instrument may occur.

  * These opcodes actually run only at i-time. Performance time copying
    is done by the user opcode call. This means that skipping xin or
    xout with kgoto has no effect, while skipping with igoto affects
    both init and performance time operation.

  Syntax

xinarg1 [, xinarg2] ... [xinargN] xin

  Performance

xinarg1, xinarg2, ... - input arguments. The number and type of
variables must agree with the user-defined opcode's intypes declaration.
However, xin does not check for incorrect use of init-time and
control-rate variables.

The syntax of a user-defined opcode block is as follows:

opcode  name, outtypes, intypes
xinarg1 [, xinarg2] [, xinarg3] ... [xinargN]  xin
[setksmps  iksmps]
... the rest of the instrument's code.
xout  xoutarg1 [, xoutarg2] [, xoutarg3] ... [xoutargN]
endop

The new opcode can then be used with the usual syntax:

[xinarg1] [, xinarg2] ... [xinargN]  name  [xoutarg1] [, xoutarg2] ... [xoutargN] [, iksmps]


===========================================================================
xout                                                                   *xout*

  Description

The xin and xout opcodes copy variables to and from the opcode
definition, allowing communication with the calling instrument.

The types of input and output variables are defined by the parameters
intypes and outtypes.

  Notes

  * xin and xout should be called only once, and xin should precede
    xout, otherwise an init error and deactivation of the current
    instrument may occur.

  * These opcodes actually run only at i-time. Performance time copying
    is done by the user opcode call. This means that skipping xin or
    xout with kgoto has no effect, while skipping with igoto affects
    both init and performance time operation.

  Syntax

xout xoutarg1 [, xoutarg2] ... [, xoutargN]

  Performance

xoutarg1, xoutarg2, ... - output arguments. The number and type of
variables must agree with the user-defined opcode's outtypes
declaration. However, xout does not check for incorrect use of init-time
and control-rate variables.

The syntax of a user-defined opcode block is as follows:

opcode  name, outtypes, intypes
xinarg1 [, xinarg2] [, xinarg3] ... [xinargN]  xin
[setksmps  iksmps]
... the rest of the instrument's code.
xout  xoutarg1 [, xoutarg2] [, xoutarg3] ... [xoutargN]
endop

The new opcode can then be used with the usual syntax:

[xinarg1] [, xinarg2] ... [xinargN]  name  [xoutarg1] [, xoutarg2] ... [xoutargN] [, iksmps]


===========================================================================
xscanmap                                                           *xscanmap*

  Description

Allows the position and velocity of a node in a scanned process to be read.

  Syntax

kpos, kvel xscanmap iscan, kamp, kvamp [, iwhich]

  Initialization

iscan -- which scan process to read

iwhich (optional) -- which node to sense. The default is 0.

  Performance

kamp -- amount to amplify the kpos value.

kvamp -- amount to amplify the kvel value.

The internal state of a node is read. This includes its position and
velocity. They are amplified by the kamp and kvamp values.


===========================================================================
xscansmap                                                         *xscansmap*

  Description

Allows the position and velocity of a node in a scanned process to be read.

  Syntax

xscansmap kpos, kvel, iscan, kamp, kvamp [, iwhich]

  Initialization

iscan -- which scan process to read

iwhich (optional) -- which node to sense. The default is 0.

  Performance

kpos -- the node's position.

kvel -- the node's velocity.

kamp -- amount to amplify the kpos value.

kvamp -- amount to amplify the kvel value.

The internal state of a node is read. This includes its position and
velocity. They are amplified by the kamp and kvamp values.


===========================================================================
xscans                                                               *xscans*

  Description

Experimental version of scans. Allows much larger matrices and is faster
and smaller but removes some (unused?) flexibility. If liked, it will
replace the older opcode as it is syntax compatible but extended.

  Syntax

ares xscans kamp, kfreq, ifntraj, id [, iorder]

  Initialization

ifntraj -- table containing the scanning trajectory. This is a series of
numbers that contains addresses of masses. The order of these addresses
is used as the scan path. It should not contain values greater than the
number of masses, or negative numbers. See the introduction to the
scanned synthesis section.

id -- If positive, the ID of the opcode. This will be used to point the
scanning opcode to the proper waveform maker. If this value is negative,
the absolute of this value is the wavetable on which to write the
waveshape. That wavetable can be used later from an other opcode to
generate sound. The initial contents of this table will be destroyed.

iorder (optional, default=0) -- order of interpolation used internally.
It can take any value in the range 1 to 4, and defaults to 4, which is
quartic interpolation. The setting of 2 is quadratic and 1 is linear.
The higher numbers are slower, but not necessarily better.

  Performance

kamp -- output amplitude. Note that the resulting amplitude is also
dependent on instantaneous value in the wavetable. This number is
effectively the scaling factor of the wavetable.

kfreq -- frequency of the scan rate

Matrix Format

The new matrix format is a list of connections, one per line linking
point x to point y. There is no weight given to the link; it is assumed
to be unity. The list is preceded by the line <MATRIX> and ends with a
</MATRIX> line

For example, a circular string of 8 would be coded as

<MATRIX>
0 1
1 0
1 2
2 1
2 3
3 2
3 4
4 3
4 5
5 4
5 6
6 5
6 7
7 6
0 7
</MATRIX>


===========================================================================
xscanu                                                               *xscanu*

  Description

Experimental version of scanu. Allows much larger matrices and is faster
and smaller but removes some (unused?) flexibility. If liked, it will
replace the older opcode as it is syntax compatible but extended.

  Syntax

xscanu init, irate, ifnvel, ifnmass, ifnstif, ifncentr, ifndamp, kmass, \
      kstif, kcentr, kdamp, ileft, iright, kpos, kstrngth, ain, idisp, id

  Initialization

init -- the initial position of the masses. If this is a negative
number, then the absolute of init signifies the table to use as a hammer
shape. If init > 0, the length of it should be the same as the intended
mass number, otherwise it can be anything.

irate -- update rate.

ifnvel -- the ftable that contains the initial velocity for each mass.
It should have the same size as the intended mass number.

ifnmass -- ftable that contains the mass of each mass. It should have
the same size as the intended mass number.

ifnstif --

  * either an ftable that contains the spring stiffness of each
    connection. It should have the same size as the square of the
    intended mass number. The data ordering is a row after row dump of
    the connection matrix of the system.

  * or a string giving the name of a file in the MATRIX format

ifncentr -- ftable that contains the centering force of each mass. It
should have the same size as the intended mass number.

ifndamp -- the ftable that contains the damping factor of each mass. It
should have the same size as the intended mass number.

ileft -- If init < 0, the position of the left hammer (ileft = 0 is hit
at leftmost, ileft = 1 is hit at rightmost).

iright -- If init < 0, the position of the right hammer (iright = 0 is
hit at leftmost, iright = 1 is hit at rightmost).

idisp -- If 0, no display of the masses is provided.

id -- If positive, the ID of the opcode. This will be used to point the
scanning opcode to the proper waveform maker. If this value is negative,
the absolute of this value is the wavetable on which to write the
waveshape. That wavetable can be used later from an other opcode to
generate sound. The initial contents of this table will be destroyed.

  Performance

kmass -- scales the masses

kstif -- scales the spring stiffness

kcentr -- scales the centering force

kdamp -- scales the damping

kpos -- position of an active hammer along the string (kpos = 0 is
leftmost, kpos = 1 is rightmost). The shape of the hammer is determined
by init and the power it pushes with is kstrngth.

kstrngth -- power that the active hammer uses

ain -- audio input that adds to the velocity of the masses. Amplitude
should not be too great.

Matrix Format

The new matrix format is a list of connections, one per line linking
point x to point y. There is no weight given to the link; it is assumed
to be unity. The list is proceeded by the line <MATRIX> and ends with a
</MATRIX> line

For example, a circular string of 8 would be coded as

<MATRIX>
0 1
1 0
1 2
2 1
2 3
3 2
3 4
4 3
4 5
5 4
5 6
6 5
6 7
7 6
0 7
</MATRIX>


===========================================================================
xtratim                                                             *xtratim*

  Description

Extend the duration of real-time generated events and handle their extra
life (Usually for usage along with release instead of linenr, linsegr,
etc).

  Syntax

xtratim iextradur

  Initialization

iextradur -- additional duration of current instrument instance

  Performance

xtratim extends current MIDI-activated note duration by iextradur
seconds after the corresponding noteoff message has deactivated the
current note itself. It is usually used in conjunction with release.
This opcode has no output arguments.

This opcode is useful for implementing complex release-oriented
envelopes, whose duration is not known when the envelope starts (e.g.
for real-time MIDI generated events).


===========================================================================
xyin                                                                   *xyin*

  Description

Sense the cursor position in an output window. When xyin is called the
position of the mouse within the output window is used to reply to the
request. This simple mechanism does mean that only one xyin can be used
accurately at once. The position of the mouse is reported in the output
window.

  Syntax

kx, ky xyin iprd, ixmin, ixmax, iymin, iymax [, ixinit] [, iyinit]

  Initialization

iprd -- period of cursor sensing (in seconds). Typically .1 seconds.

xmin, xmax, ymin, ymax -- edge values for the x-y coordinates of a
cursor in the input window.

ixinit, iyinit (optional) -- initial x-y coordinates reported; the
default values are 0,0. If these values are not within the given min-max
range, they will be coerced into that range.

  Performance

xyin samples the cursor x-y position in an input window every iprd
seconds. Output values are repeated (not interpolated) at the k-rate,
and remain fixed until a new change is registered in the window. There
may be any number of input windows. This unit is useful for real-time
control, but continuous motion should be avoided if iprd is unusually
small.

  Note

Depending on your platform and distribution, you might need to enable
displays using the --displays command line flag.


===========================================================================
zacl                                                                   *zacl*

  Description

Clears one or more variables in the za space.

  Syntax

zacl kfirst, klast

  Performance

kfirst -- first zk or za location in the range to clear.

klast -- last zk or za location in the range to clear.

zacl clears one or more variables in the za space. This is useful for
those variables which are used as accumulators for mixing a-rate signals
at each cycle, but which must be cleared before the next set of
calculations.


===========================================================================
zakinit                                                             *zakinit*

  Description

Establishes zak space. Must be called only once.

  Syntax

zakinit isizea, isizek

  Initialization

isizea -- the number of audio rate locations for a-rate patching. Each
location is actually an array which is ksmps long.

isizek -- the number of locations to reserve for floats in the zk space.
These can be written and read at i- and k-rates.

  Performance

At least one location each is always allocated for both za and zk
spaces. There can be thousands or tens of thousands za and zk ranges,
but most pieces probably only need a few dozen for patching signals.
These patching locations are referred to by number in the other zak
opcodes.

To run zakinit only once, put it outside any instrument definition, in
the orchestra file header, after sr, kr, ksmps, and nchnls.

  Note

Zak channels count from 0, so if you define 1 channel, the only valid
channel is channel 0.


===========================================================================
zamod                                                                 *zamod*

  Description

Modulates one a-rate signal by a second one.

  Syntax

ares zamod asig, kzamod

  Performance

asig -- the input signal

kzamod -- controls which za variable is used for modulation. A positive
value means additive modulation, a negative value means multiplicative
modulation. A value of 0 means no change to asig.

zamod modulates one a-rate signal by a second one, which comes from a za
variable. The location of the modulating variable is controlled by the
i-rate or k-rate variable kzamod. This is the a-rate version of zkmod.


===========================================================================
zar                                                                     *zar*

  Description

Reads from a location in za space at a-rate.

  Syntax

ares zar kndx

  Performance

kndx -- points to the za location to be read.

zar reads the array of floats at kndx in za space, which are ksmps
number of a-rate floats to be processed in a k cycle.


===========================================================================
zarg                                                                   *zarg*

  Description

Reads from a location in za space at a-rate, adds some gain.

  Syntax

ares zarg kndx, kgain

  Initialization

kndx -- points to the za location to be read.

kgain -- multiplier for the a-rate signal.

  Performance

zarg reads the array of floats at kndx in za space, which are ksmps
number of a-rate floats to be processed in a k cycle. zarg also
multiplies the a-rate signal by a k-rate value kgain.


===========================================================================
zaw                                                                     *zaw*

  Description

Writes to a za variable at a-rate without mixing.

  Syntax

zaw asig, kndx

  Performance

asig -- value to be written to the za location.

kndx -- points to the zk or za location to which to write.

zaw writes asig into the za variable specified by kndx.

These opcodes are fast, and always check that the index is within the
range of zk or za space. If not, an error is reported, 0 is returned,
and no writing takes place.


===========================================================================
zawm                                                                   *zawm*

  Description

Writes to a za variable at a-rate with mixing.

  Syntax

zawm asig, kndx [, imix]

  Initialization

imix (optional, default=1) -- indicates if mixing should occur.

  Performance

asig -- value to be written to the za location.

kndx -- points to the zk or za location to which to write.

These opcodes are fast, and always check that the index is within the
range of zk or za space. If not, an error is reported, 0 is returned,
and no writing takes place.

zawm is a mixing opcode, it adds the signal to the current value of the
variable. If no imix is specified, mixing always occurs. imix = 0 will
cause overwriting like ziw, zkw, and zaw. Any other value will cause
mixing.

Caution: When using the mixing opcodes ziwm, zkwm, and zawm, care must
be taken that the variables mixed to, are zeroed at the end (or start)
of each k- or a-cycle. Continuing to add signals to them, can cause
their values can drift to astronomical figures.

One approach would be to establish certain ranges of zk or za variables
to be used for mixing, then use zkcl or zacl to clear those ranges.


===========================================================================
zfilter2                                                           *zfilter2*

  Description

General purpose custom filter with time-varying pole control. The filter
coefficients implement the following difference equation:

(1)*y(n) = b0*x[n] + b1*x[n-1] +...+ bM*x[n-M] - a1*y[n-1] -...- aN*y[n-N]

the system function for which is represented by:

           B(Z)      b0 + b1*Z^-1   + ... + bM*Z^-M
  H(Z)  =  ----  =  --------------------------
           A(Z)       1 + a1*Z^-1   + ... + aN*Z^-N

  Syntax

ares zfilter2 asig, kdamp, kfreq, iM, iN, ib0, ib1, ..., ibM, \
      ia1,ia2, ..., iaN

  Initialization

At initialization the number of zeros and poles of the filter are
specified along with the corresponding zero and pole coefficients. The
coefficients must be obtained by an external filter-design application
such as Matlab and specified directly or loaded into a table via GEN01.
With zfilter2, the roots of the characteristic polynomials are solved at
initialization so that the pole-control operations can be implemented
efficiently.

  Performance

The filter2 opcodes perform filtering using a transposed form-II digital
filter lattice with no time-varying control. zfilter2 uses the
additional operations of radial pole-shearing and angular pole-warping
in the Z plane.

Pole shearing increases the magnitude of poles along radial lines in the
Z-plane. This has the affect of altering filter ring times. The k-rate
variable kdamp is the damping parameter. Positive values (0.01 to 0.99)
increase the ring-time of the filter (hi-Q), negative values (-0.01 to
-0.99) decrease the ring-time of the filter, (lo-Q).

Pole warping changes the frequency of poles by moving them along angular
paths in the Z plane. This operation leaves the shape of the magnitude
response unchanged but alters the frequencies by a constant factor
(preserving 0 and p). The k-rate variable kfreq determines the frequency
warp factor. Positive values (0.01 to 0.99) increase frequencies toward
p and negative values (-0.01 to -0.99) decrease frequencies toward 0.

Since filter2 implements generalized recursive filters, it can be used
to specify a large range of general DSP algorithms. For example, a
digital waveguide can be implemented for musical instrument modeling
using a pair of delayr and delayw opcodes in conjunction with the
filter2 opcode.


===========================================================================
zir                                                                     *zir*

  Description

Reads from a location in zk space at i-rate.

  Syntax

ir zir indx

  Initialization

indx -- points to the zk location to be read.

  Performance

zir reads the signal at indx location in zk space.


===========================================================================
ziw                                                                     *ziw*

  Description

Writes to a zk variable at i-rate without mixing.

  Syntax

ziw isig, indx

  Initialization

isig -- initializes the value of the zk location.

indx -- points to the zk or za location to which to write.

  Performance

ziw writes isig into the zk variable specified by indx.

These opcodes are fast, and always check that the index is within the
range of zk or za space. If not, an error is reported, 0 is returned,
and no writing takes place.


===========================================================================
ziwm                                                                   *ziwm*

  Description

Writes to a zk variable to an i-rate variable with mixing.

  Syntax

ziwm isig, indx [, imix]

  Initialization

isig -- initializes the value of the zk location.

indx -- points to the zk location location to which to write.

imix (optional, default=1) -- indicates if mixing should occur.

  Performance

ziwm is a mixing opcode, it adds the signal to the current value of the
variable. If no imix is specified, mixing always occurs. imix = 0 will
cause overwriting like ziw, zkw, and zaw. Any other value will cause
mixing.

Caution: When using the mixing opcodes ziwm, zkwm, and zawm, care must
be taken that the variables mixed to, are zeroed at the end (or start)
of each k- or a-cycle. Continuing to add signals to them, can cause
their values can drift to astronomical figures.

One approach would be to establish certain ranges of zk or za variables
to be used for mixing, then use zkcl or zacl to clear those ranges.


===========================================================================
zkcl                                                                   *zkcl*

  Description

Clears one or more variables in the zk space.

  Syntax

zkcl kfirst, klast

  Performance

ksig -- the input signal

kfirst -- first zk or za location in the range to clear.

klast -- last zk or za location in the range to clear.

zkcl clears one or more variables in the zk space. This is useful for
those variables which are used as accumulators for mixing k-rate signals
at each cycle, but which must be cleared before the next set of
calculations.


===========================================================================
zkmod                                                                 *zkmod*

  Description

Facilitates the modulation of one signal by another.

  Syntax

kres zkmod ksig, kzkmod

  Performance

ksig -- the input signal

kzkmod -- controls which zk variable is used for modulation. A positive
value means additive modulation, a negative value means multiplicative
modulation. A value of 0 means no change to ksig. kzkmod can be i-rate
or k-rate

zkmod facilitates the modulation of one signal by another, where the
modulating signal comes from a zk variable. Either additive or
mulitiplicative modulation can be specified.


===========================================================================
zkr                                                                     *zkr*

  Description

Reads from a location in zk space at k-rate.

  Syntax

kres zkr kndx

  Initialization

kndx -- points to the zk location to be read.

  Performance

zkr reads the array of floats at kndx in zk space.


===========================================================================
zkw                                                                     *zkw*

  Description

Writes to a zk variable at k-rate without mixing.

  Syntax

zkw ksig, kndx

  Performance

ksig -- value to be written to the zk location.

kndx -- points to the zk or za location to which to write.

zkw writes ksig into the zk variable specified by kndx.


===========================================================================
zkwm                                                                   *zkwm*

  Description

Writes to a zk variable at k-rate with mixing.

  Syntax

zkwm ksig, kndx [, imix]

  Initialization

imix (optional, default=1) -- indicates if mixing should occur.

  Performance

ksig -- value to be written to the zk location.

kndx -- points to the zk or za location to which to write.

zkwm is a mixing opcode, it adds the signal to the current value of the
variable. If no imix is specified, mixing always occurs. imix = 0 will
cause overwriting like ziw, zkw, and zaw. Any other value will cause
mixing.

Caution: When using the mixing opcodes ziwm, zkwm, and zawm, care must
be taken that the variables mixed to, are zeroed at the end (or start)
of each k- or a-cycle. Continuing to add signals to them, can cause
their values can drift to astronomical figures.

One approach would be to establish certain ranges of zk or za variables
to be used for mixing, then use zkcl or zacl to clear those ranges.


===========================================================================
a Statement (or Advance Statement)                                 *a (sco)*

  Description

This causes score time to be advanced by a specified amount without
producing sound samples.

  Syntax

a p1  p2  p3

  Performance

  p1    Carries no meaning. Usually zero.
  p2    Action time, in beats, at which advance is to begin.
  p3    Number of beats to advance without producing sound.
  p4    |
  p5    |    These carry no meaning.
  p6    |
  .
  .

      Special Considerations

This statement allows the beat count within a score section to be
advanced without generating intervening sound samples. This can be of
use when a score section is incomplete (the beginning or middle is
missing) and the user does not wish to generate and listen to a lot of
silence.

p2, action time, and p3, number of beats, are treated as in i
statements, with respect to sorting and modification by t statements.

An a statement will be temporarily inserted in the score by the Score
Extract feature when the extracted segment begins later than the start
of a Section. The purpose of this is to preserve the beat count and time
count of the original score for the benefit of the peak amplitude
messages which are reported on the user console.

Whenever an a statement is encountered by a performing orchestra, its
presence and effect will be reported on the user's console.


===========================================================================
b Statement                                                               *b*

  Description

This statement resets the clock.

  Syntax

b p1

  Performance

p1 -- Specifies how the clock is to be set.

      Special Considerations

p1 is the number of beats by which p2 values of subsequent i statements
are modified. If p1 is positive, the clock is reset forward, and
subsequent notes appear later, the number of beats specified by p1 being
added to the note's p2. If p1 is negative, the clock is reset backward,
and subsequent notes appear earlier, the number of beats specified by p1
being subtracted from the note's p2. There is no cumulative affect. The
clock is reset with each b statement. If p1 = 0, the clock is returned
to its original position, and subsequent notes appear at their specified
p2.


===========================================================================
e Statement                                                               *e*

  Description

This statement may be used to mark the end of the last section of the
score.

  Syntax

e [time]

  Performance

The first p-field time is optional and if present determines the end
time (length in beats) of the final section of the score. This time must
be after the end of the last event otherwise it will have no effect.
"Always on" instruments will end at the given time. Extending the
section in this way is useful to avoid prematurely cutting off reverb
tails or other effects.

      Special Considerations

The e statement is contextually identical to an s statement.
Additionally, the e statement terminates all signal generation
(including indefinite performance) and closes all input and output files.

If an e statement occurs before the end of a score, all subsequent score
lines will be ignored.

The e statement is optional in a score file yet to be sorted. If a score
file has no e statement, then Sort processing will supply one.


===========================================================================
f Statement (or Function Table Statement)                                 *f*

  Description

This causes a GEN subroutine to place values in a stored function table
for use by instruments.

  Syntax

f p1  p2  p3  p4  p5 ... PMAX

  Performance

p1 -- Table number by which the stored function will be known. A
negative number requests that the table be destroyed.

p2 -- Action time of function generation (or destruction) in beats.

p3 -- Size of function table (i.e. number of points) Must be a power of
2, or a power-of-2 plus 1 if this number is positive. Maximum table size
is 16777216 (2^24 ) points.

p4 -- Number of the GEN routine to be called (see GEN ROUTINES). A
negative value will cause rescaling to be omitted.

p5 ... PMAX -- Parameters whose meaning is determined by the particular
GEN routine.

      Special Considerations

Function tables are arrays of floating-point values. You can create a
simple sine wave using the line:

f 1 0 1024 10 1

This table uses GEN10 to fill the table.

Historically, due to older platform constraints, Csound could only
accept tables whose size was a power of two. This limitation has been
removed in recent versions, and you can freely create tables of any
size. However, to create a table whose size is not a power of two (or
power of two plus one), you must specify the size as a negative number.

  Note

Not all opcodes accept tables whose size is not a power of two, since
they may depend on this for internal optimization.

For arrays whose length is a power of 2, space allocation always
provides for 2^n points plus an additional guard point. The guard point
value, used during interpolated lookup, can be automatically set to
reflect the table's purpose: If size is an exact power of 2, the guard
point will be a copy of the first point; this is appropriate for
interpolated wrap-around lookup as in oscili, etc., and should even be
used for non-interpolating oscil for safe consistency. If size is set to
2 ^n + 1, the guard point value automatically extends the contour of
table values; this is appropriate for single-scan functions such in
envplx, oscil1, oscil1i, etc.

The size of the table is used as a code to tell Csound how to fill this
guard-point. If the size is exactly power-of-two, then the guard point
contains a copy of the first point on the table. If the size is
power-of-two plus one, Csound will extend the contour of the function
stored in the table for one extra point.

Table space is allocated in primary memory, along with instrument data
space. The maximum table number used to be 200. This has been changed to
be limited by memory only. (Currently there is an internal soft limit of
300, this is automatically extended as required.)

An existing function table can be removed by an f statement containing a
negative p1 and an appropriate action time. A function table can also be
removed by the generation of another table with the same p1. Functions
are not automatically erased at the end of a score section.

p2 action time is treated in the same way as in i statements with
respect to sorting and modification by t statements. If an f statement
and an i statement have the same p2, the sorter gives the f statement
precedence so that the function table will be available during note
initialization.

  Warning

The maximum number of p-fields accepted in the score is determined by
PMAX (a compilation time varible). PMAX is currently set to 1000. This
may discard values entered when using GEN02. To overcome this, use GEN23
or GEN28 to read the values from a file.

An f 0 statement (zero p1, positive p2) may be used to create an action
time with no associated action. Such time markers are useful for padding
out a score section (see s statement) and for letting Csound run from
realtime events only (e.g. using only MIDI input without score events).
The time given is the number of seconds Csound will run. If you want
Csound to run for 10 hours, use:

f0 36000

The simplest way to fill a table (f1) with 0's is:

f1 0 xx 2 0

where xx = table size.

The simplest way to fill a table (f1) with *any* single value is:

f1 0 xx -7 yy xx yy

where xx = table size and yy = any single value

In both of the above examples, table size (p3) must be a power of 2 or
power-of-2 plus 1.


===========================================================================
i Statement (Instrument or Note Statement)                         *i (sco)*

  Description

This statement calls for an instrument to be made active at a specific
time and for a certain duration. The parameter field values are passed
to that instrument prior to its initialization, and remain valid
throughout its Performance.

  Syntax

i  p1  p2  p3  p4  ...

  Initialization

p1 -- Instrument number, usually a non-negative integer. An optional
fractional part can provide an additional tag for specifying ties
between particular notes of consecutive clusters. A negative p1
(including tag) can be used to turn off a particular “held” note.

p2 -- Starting time in arbitrary units called beats.

p3 -- Duration time in beats (usually positive). A negative value will
initiate a held note (see also ihold). A negative value can also be used
for 'always on' instruments like reverberation. These notes are not
terminated by s statements A zero value will invoke an initialization
pass without performance (see also instr).

p4 ... -- Parameters whose significance is determined by the instrument.

  Performance

Beats are evaluated as seconds, unless there is a t statement in this
score section or a -t flag in the command-line.

Starting or action times are relative to the beginning of a section (
see s statement), which is assigned time 0.

Note statements within a section may be placed in any order. Before
being sent to an orchestra, unordered score statements must first be
processed by Sorter, which will reorder them by ascending p2 value.
Notes with the same p2 value will be ordered by ascending p1; if the
same p1, then by ascending p3.

Notes may be stacked, i.e., a single instrument can perform any number
of notes simultaneously. (The necessary copies of the instrument's data
space will be allocated dynamically by the orchestra loader.) Each note
will normally turn off when its p3 duration has expired, or on receipt
of a MIDI noteoff signal. An instrument can modify its own duration
either by changing its p3 value during note initialization, or by
prolonging itself through the action of a linenr or xtratim unit.

An instrument may be turned on and left to perform indefinitely either
by giving it a negative p3 or by including an ihold in its i-time code.
If a held note is active, an i statement with matching p1 will not cause
a new allocation but will take over the data space of the held note. The
new pfields (including p3) will now be in effect, and an i-time pass
will be executed in which the units can either be newly initialized or
allowed to continue as required for a tied note (see tigoto). A held
note may be succeeded either by another held note or by a note of finite
duration. A held note will continue to perform across section endings
(see s statement). It is halted only by turnoff or by an i statement
with negative matching p1 or by an e statement.

It is possible to have multiple instances (usually, but not necessarily,
notes of different pitches) of the same instrument, held simultaneously,
via negative p3 values. The instrument can then be fed new parameters
from the score. This is useful for avoiding long hard-coded linsegs, and
can be accomplished by adding a decimal part to the instrument number.

For example, to hold three copies of instrument 10 in a simple chord:

i10.1    0    -1    7.00
i10.2    0    -1    7.04
i10.3    0    -1    7.07

Subsequent i statements can refer to the same sounding note instances,
and if the instrument definition is done properly, the new p-fields can
be used to alter the character of the notes in progress. For example, to
bend the previous chord up an octave and release it:

i10.1    1    1    8.00
i10.2    1    1    8.04
i10.3    1    1    8.07

  Tip

When turning off notes, bear in mind that i 1.1 == i 1.10 and i 1.1 != i
1.01. The maximum number of decimal places that can be used depends on
the precision Csound was compiled with (See Csound Double (64-bit) vs.
Float (32-bit))

The instrument definition has to take this into account, however,
especially if clicks are to be avoided (see the example below).

Note that the decimal instrument number notation cannot be used in
conjunction with real-time MIDI. In this case, the instrument would be
monophonic while a note was held.

Notes being tied to previous instances of the same instrument, should
skip most initialization by means of tigoto, except for the values
entered in score. For example, all table reading opcodes in the
instrument, should usually be skipped, as they store their phase
internally. If this is suddenly changed, there will be audible clicks in
the output.

Note that many opcodes (such as delay and reverb) are prepared for
optional initialization. To use this feature, the tival opcode is
suitable. Therefore, they need not be hidden by a tigoto jump.

Beginning with Csound version 3.53, strings are recognized in p-fields
for opcodes that accept them (convolve, adsyn, diskin, etc.). There may
be only one string per score line.

You can also turnoff notes from the score by using a negative number for
the instrument (p1). This is equivalent to using the turnoff2 opcode.
When a note is turned off from the score, it is allowed to release (if
xtratim or opcodes with release section like linenr are used) and only
notes with the same fractional part are turned off. Also, only the last
instance of the instrument will be turned off, so there have to be as
many negative instrument numbers as positive ones for all notes to be
turned off.

i 1.1    1    300    8.00
i 1.2    1    300    8.04
i 1.3    1    -300    8.07
i 1.3    1    -300    8.09

; notice that p-fields after p2 will be ignored if 
; instrument number is negative
i -1.1    3    1    4.00
i -1.2    4    51    4.04
i -1.3    5    1    4.07
i -1.3    6    10    4.09

      Special Considerations

The maximum instrument number used to be 200. This has been changed to
be limited by memory only (currently there is an internal soft limit of
200; this is automatically extended as required).


===========================================================================
m Statement (Mark Statement)                                              *m*

  Description

Sets a named mark in the score, which can be used by an n statement.

  Syntax

m p1

  Initialization

p1 -- Name of mark.

  Performance

This can be helpful in setting a up verse and chorus structure in the
score. Names may contain letters and numerals.

For example, the following score:

m foo
i1 0 1
i1 1 1.5
i1 2.5 2
s
i1 0 10
s
n foo
e

Will be passed from the preprocessor to Csound as:

i1 0 1
i1 1 1.5
i1 2.5 2
s
i1 0 10
s
;; this is named section repeated
i1 0 1
i1 1 1.5
i1 2.5 2
s
;; end of named section
e


===========================================================================
n Statement                                                               *n*

  Description

Repeats a section from the referenced m statement.

  Syntax

n p1

  Initialization

p1 -- Name of mark to repeat.

  Performance

This can be helpful in setting a up verse and chorus structure in the
score. Names may contain letters and numerals.

For example, the following score:

m foo
i1 0 1
i1 1 1.5
i1 2.5 2
s
i1 0 10
s
n foo
e

Will be passed from the preprocessor to Csound as:

i1 0 1
i1 1 1.5
i1 2.5 2
s
i1 0 10
s
;; this is named section repeated
i1 0 1
i1 1 1.5
i1 2.5 2
s
;; end of named section
e


===========================================================================
q Statement                                                               *q*

  Description

This statement may be used to quiet an instrument.

  Syntax

q p1  p2  p3

  Performance

p1 -- Instrument number to mute/unmute.

p2 -- Action time in beats.

p3 -- determines whether the instrument is muted/unmuted. The value of 0
means the instrument is muted, other values mean it is unmuted.

Note that this does not affect instruments that are already running at
time p2. It blocks any attempt to start one afterwards.


===========================================================================
r Statement (Repeat Statement)                                            *r*

  Description

Starts a repeated section, which lasts until the next s, r or e statement.

  Syntax

r p1 p2

  Initialization

p1 -- Number of times to repeat the section.

p2 -- Macro(name) to advance with each repetition (optional).

  Performance

In order that the sections may be more flexible than simple editing, the
macro named p2 is given the value of 1 for the first time through the
section, 2 for the second, and 3 for the third. This can be used to
change p-field parameters, or ignored.

  Warning

Because of serious problems of interaction with macro expansion,
sections must start and end in the same file, and not in a macro.


===========================================================================
s Statement                                                               *s*

  Description

The s statement marks the end of a section.

  Syntax

s [time]

  Initialization

The first p-field time is optional and if present determines the end
time (length in beats) of the section. This time must be after the end
of the last event in the section otherwise it will have no effect. This
can be used to create a pause before the beginning of the next section
or to allow "always on" instruments such as effects to play by
themselves for some length of time.

  Performance

Sorting of the i statement, f statement and a statement by action time
is done section by section.

Time warping for the t statement is done section by section.

All action times within a section are relative to its beginning. A
section statement establishes a new relative time of 0, but has no other
reinitializing effects (e.g. stored function tables are preserved across
section boundaries).

A section is considered complete when all action times and finite
durations have been satisfied (i.e., the "length" of a section is
determined by the last occurring action or turn-off). A section can be
extended by the use of an f0 statement or by supplying the optional p1
value to the s statement.

A section ending automatically invokes a purge of inactive instrument
and data spaces.

  Note

  * Since score statements are processed section by section, the amount
    of memory required depends on the maximum number of score statements
    in a section. Memory allocation is dynamic, and the user will be
    informed as extra memory blocks are requested during score processing.

  * For the end of the final section of a score, the s statement is
    optional; the e statement may be used instead.


===========================================================================
t Statement (Tempo Statement)                                             *t*

  Description

This statement sets the tempo and specifies the accelerations and
decelerations for the current section. This is done by converting beats
into seconds.

  Syntax

t  p1  p2  p3  p4 ... (unlimited)

  Initialization

p1 -- Must be zero.

p2 -- Initial tempo on beats per minute.

p3, p5, p7,... -- Times in beats (in non-decreasing order).

p4, p6, p8,... -- Tempi for the referenced beat times.

  Performance

Time and Tempo-for-that-time are given as ordered couples that define
points on a "tempo vs. time" graph. (The time-axis here is in beats so
is not necessarily linear.) The beat-rate of a Section can be thought of
as a movement from point to point on that graph: motion between two
points of equal height signifies constant tempo, while motion between
two points of unequal height will cause an accelarando or ritardando
accordingly. The graph can contain discontinuities: two points given
equal times but different tempi will cause an immediate tempo change.

Motion between different tempos over non-zero time is inverse linear.
That is, an accelerando between two tempos M1 and M2 proceeds by linear
interpolation of the single-beat durations from 60/M1 to 60/M2.

The first tempo given must be for beat 0.

A tempo, once assigned, will remain in effect from that time-point
unless influenced by a succeeding tempo, i.e. the last specified tempo
will be held to the end of the section.

A t statement applies only to the score section in which it appears.
Only one t statement is meaningful in a section; it can be placed
anywhere within that section. If a score section contains no t
statement, then beats are interpreted as seconds (i.e. with an implicit
t 0 60 statement).

N.B. If the CSound command includes a -t flag, the interpreted tempo of
all score t statements will be overridden by the command-line tempo.


===========================================================================
v Statement                                                               *v*

  Description

The v statement provides for locally variable time warping of score events.

  Syntax

v p1

  Initialization

p1 -- Time warp factor (must be positive).

  Performance

The v statement takes effect with the following i statement, and remains
in effect until the next v statement, s statement, or e statement.


===========================================================================
x Statement                                                               *x*

  Description

This statement may be used to skip the rest of the current section.

  Syntax

x anything

  Initialization

All pfields are ignored.


===========================================================================
y Statement (or Seed Statement)                                           *y*

  Description

Set seed for random numbers, either from p1 or, if omitted, the clock.

  Syntax

y [p1]

  Initialization

p1 -- An integer value between 0 and 2^32 used as a new seed for random
numbers. If omitted, the system clock value will be used instead.

  Performance

The tilde symbol ˜ can be used in an expression wherever a number is
permissible to use. Each ˜ will evaluate to a random value between zero
(0) and one (1). If there is no y statement in the score, the
pseudo-random generator will yield the same numbers in each performance.
If a fixed seed is given, a different predictable series of
pseudo-random numbers will be generated from this seed. If a y statement
is used without p1, the system clock will be used as a seed, yielding a
different series of pseudo-random numbers for each performance.


===========================================================================
{ Statement                                                               *{*

  Description

The { and } statements can be used to repeat a group of score
statements. These loops do not constitute independent score sections and
thus may repeat events within the same section. Multiple loops may
overlap in time or be nested within each other.

  Syntax

{ p1 p2

  Initialization

p1 -- Number of times to repeat the loop.

p2 -- A macro name that is automatically defined at the beginning of the
loop and whose value is advanced with each repetition (optional). The
initial value is zero and the final value is (p1 - 1).

  Performance

The { statement is used in conjunction with the } statement to define
repeating groups of other score events. A score loop begins with the {
statement which defines the number of repetitions and a unique macro
name that will contain the current loop counter. The body of a loop can
contain any number of other events (including sectional breaks) and is
terminated by a } statement on its own line. The } statement takes no
parameters.

The use of the term "loop" here does not imply any sort of temporal
succession to the loop iterations. In other words, the p2 values of the
events inside of the loop are not automatically incremented by the
length of the loop in each repetition. This is actually an advantage
since it allows groups of simulataneous events to be easily defined as
well. The loop macro can be used along with score expressions to
increase the start times of events or to vary the events in any other
way desired for each iteration. The macro is incremented by one for each
repetition. Note that unlike the r statement, the value of the macro the
first time through the loop is zero (0), not one (1). Therefore the
final value is one less than the number of repetitions.

Score loops are a very powerful tool. While similar to the section
repeat facility (the r statement), their chief advantage is that the
score events in successive iterations of the loop are not separated by a
section termination. Thus, it is possible to create multiple loops that
overlap in time. Loops also can be nested within each other to a depth
of 39 levels.

  Warning

Because of serious problems of interaction with macro expansion, loops
must start and end in the same file, and not in a macro.


===========================================================================
} Statement                                                               *}*

  Description

The { and } statements can be used to repeat a group of score
statements. These loops do not constitute independent score sections and
thus may repeat events within the same section. Multiple loops may
overlap in time or be nested within each other.

  Syntax

}

  Initialization

All pfields are ignored.

  Performance

The } statement is used in conjunction with the { statement to define
repeating groups of other score events. A score loop begins with the {
statement which defines the number of repetitions and a unique macro
name that will contain the current loop counter. The body of a loop can
contain any number of other events (including sectional breaks) and is
terminated by a } statement on its own line. The } statement takes no
parameters.

See the documentation for the { statement for further details.


===========================================================================
GEN01                                                                 *GEN01*

  Description

This subroutine transfers data from a soundfile into a function table.

  Syntax

f#  time  size  1  filcod  skiptime  format  channel

  Performance

size -- number of points in the table. Ordinarily a power of 2 or a
power-of-2 plus 1 (see f statement); the maximum tablesize is 16777216
(2^24 ) points. The allocation of table memory can be deferred by
setting this parameter to 0; the size allocated is then the number of
points in the file (probably not a power-of-2), and the table is not
usable by normal oscillators, but it is usable by a loscil unit. The
soundfile can also be mono or stereo.

filcod -- integer or character-string denoting the source soundfile
name. An integer denotes the file soundin.filcod ; a character-string
(in double quotes, spaces permitted) gives the filename itself,
optionally a full pathname. If not a full path, the file is sought first
in the current directory, then in that given by the environment variable
SSDIR (if defined) then by SFDIR. See also soundin.

skiptime -- begin reading at skiptime seconds into the file.

channel -- channel number to read in. 0 denotes read all channels.

format -- specifies the audio data-file format:

1 - 8-bit signed character    4 - 16-bit short integers 
2 - 8-bit A-law bytes         5 - 32-bit long integers 
3 - 8-bit U-law bytes         6 - 32-bit floats

If format = 0 the sample format is taken from the soundfile header, or
by default from the CSound -o command-line flag.

  Note

  * Reading stops at end-of-file or when the table is full. Table
    locations not filled will contain zeros.

  * If p4 is positive, the table will be post-normalized (rescaled to a
    maximum absolute value of 1 after generation). A negative p4 will
    cause rescaling to be skipped.

  * GEN01 also works with WAV and OGG and a dozen and more other sound
    formats; these file formats depend on libsndfile, see
    http://www.mega-nerd.com/libsndfile/


===========================================================================
GEN02                                                                 *GEN02*

  Description

This subroutine transfers data from immediate pfields into a function
table.

  Syntax

f # time size 2 v1 v2 v3 ...

  Initialization

size -- number of points in the table. Must be a power of 2 or a
power-of-2 plus 1 (see f statement). The maximum tablesize is 16777216
(2^24 ) points.

v1, v2, v3, etc. -- values to be copied directly into the table space.
The number of values is limited by the compile-time variable PMAX, which
controls the maximum pfields (currently 1000). The values copied may
include the table guard point; any table locations not filled will
contain zeros.

  Note

If p4 (the GEN routine number is positive, the table will be
post-normalized (rescaled to a maximum absolute value of 1 after
generation). A negative p4 will cause rescaling to be skipped. You will
usually want to use -2 with this GEN function, so that your values are
not normalized.


===========================================================================
GEN03                                                                 *GEN03*

  Description

This subroutine generates a stored function table by evaluating a
polynomial in x over a fixed interval and with specified coefficients.

  Syntax

f  #  time  size  3  xval1  xval2  c0  c1  c2  ...  cn

  Initialization

size -- number of points in the table. Must be a power of 2 or a
power-of-2 plus 1.

xval1, xval2 -- left and right values of the x interval over which the
polynomial is defined (xval1 < xval2). These will produce the 1st stored
value and the (power-of-2 plus l)th stored value respectively in the
generated function table.

c0, c1, c2, ..., cn -- coefficients of the nth-order polynomial

C_0 + C_1 x + C_2 x^2 + . . . + C_n x^n

Coefficients may be positive or negative real numbers; a zero denotes a
missing term in the polynomial. The coefficient list begins in p7,
providing a current upper limit of 144 terms.

  Note

  * The defined segment [fn(xval1), fn(xval2)] is evenly distributed.
    Thus a 512-point table over the interval [-1,1] will have its origin
    at location 257 (at the start of the 2nd half). Provided the
    extended guard point is requested, both fn(-1) and fn(1) will exist
    in the table.

  * GEN03 is useful in conjunction with table or tablei for audio
    waveshaping (sound modification by non-linear distortion).
    Coefficients to produce a particular formant from a sinusoidal
    lookup index of known amplitude can be determined at preprocessing
    time using algorithms such as Chebyshev formulae. See also GEN13.


===========================================================================
GEN04                                                                 *GEN04*

  Description

This subroutine generates a normalizing function by examining the
contents of an existing table.

  Syntax

f  #  time  size  4  source#  sourcemode

  Initialization

size -- number of points in the table. Should be power-of-2 plus 1. Must
not exceed (except by 1) the size of the source table being examined;
limited to just half that size if the sourcemode is of type offset (see
below).

source # -- table number of stored function to be examined.

sourcemode -- a coded value, specifying how the source table is to be
scanned to obtain the normalizing function. Zero indicates that the
source is to be scanned from left to right. Non-zero indicates that the
source has a bipolar structure; scanning will begin at the mid-point and
progress outwards, looking at pairs of points equidistant from the center.

  Note

  * The normalizing function derives from the progressive absolute
    maxima of the source table being scanned. The new table is created
    left-to-right, with stored values equal to 1/(absolute maximum so
    far scanned). Stored values will thus begin with 1/(first value
    scanned), then get progressively smaller as new maxima are
    encountered. For a source table which is normalized (values <= 1),
    the derived values will range from 1/(first value scanned) down to
    1. If the first value scanned is zero, that inverse will be set to 1.

  * The normalizing function from GEN04 is not itself normalized.

  * GEN04 is useful for scaling a table-derived signal so that it has a
    consistent peak amplitude. A particular application occurs in
    waveshaping when the carrier (or indexing) signal is less than full
    amplitude.


===========================================================================
GEN05                                                                 *GEN05*

  Description

Constructs functions from segments of exponential curves.

  Syntax

f # time size 5 a n1 b n2 c ...

  Initialization

size -- number of points in the table. Must be a power of 2 or
power-of-2 plus 1 (see f statement).

a, b, c, etc. -- ordinate values, in odd-numbered pfields p5, p7, p9, .
. . These must be nonzero and must be alike in sign.

n1, n2, etc. -- length of segment (no. of storage locations), in
even-numbered pfields. Cannot be negative, but a zero is meaningful for
specifying discontinuous waveforms. The sum n1 + n2 + .... will normally
equal size for fully specified functions. If the sum is smaller, the
function locations not included will be set to zero; if the sum is
greater, only the first size locations will be stored. Note that the
values are rounded to integers before use.

  Note

  * If p4 is positive, functions are post-normalized (rescaled to a
    maximum absolute value of 1 after generation). A negative p4 will
    cause rescaling to be skipped.

  * Discrete-point linear interpolation implies an increase or decrease
    along a segment by equal differences between adjacent locations;
    exponential interpolation implies that the progression is by equal
    ratio. In both forms the interpolation from a to b is such as to
    assume that the value b will be attained in the n + 1th location.
    For discontinuous functions, and for the segment encompassing the
    end location, this value will not actually be reached, although it
    may eventually appear as a result of final scaling.


===========================================================================
GEN06                                                                 *GEN06*

  Description

This subroutine will generate a function comprised of segments of cubic
polynomials, spanning specified points just three at a time.

  Syntax

f  #   time   size   6   a   n1   b   n2   c   n3   d ...

  Initialization

size -- number of points in the table. Must be a power off or power-of-2
plus 1 (see f statement).

a, c, e, ... -- local maxima or minima of successive segments, depending
on the relation of these points to adjacent inflexions. May be either
positive or negative.

b, d, f, ... -- ordinate values of points of inflexion at the ends of
successive curved segments. May be positive or negative.

n1, n2, n3 ... -- number of stored values between specified points.
Cannot be negative, but a zero is meaningful for specifying
discontinuities. The sum n1 + n2 + ... will normally equal size for
fully specified functions. (for details, see GEN05).

  Note

GEN06 constructs a stored function from segments of cubic polynomial
functions. Segments link ordinate values in groups of 3: point of
inflexion, maximum/minimum, point of inflexion. The first complete
segment encompasses b, c, d and has length n2 + n3, the next encompasses
d, e, f and has length n4 + n5, etc. The first segment (a, b with length
n1) is partial with only one inflexion; the last segment may be partial
too. Although the inflexion points b, d, f ... each figure in two
segments (to the left and right), the slope of the two segments remains
independent at that common point (i.e. the 1st derivative will likely be
discontinuous). When a, c, e... are alternately maximum and minimum, the
inflexion joins will be relatively smooth; for successive maxima or
successive minima the inflexions will be comb-like.


===========================================================================
GEN07                                                                 *GEN07*

  Description

Constructs functions from segments of straight lines.

  Syntax

f  #    time    size   7   a   n1   b   n2   c  ...

  Initialization

size -- number of points in the table. Must be a power of 2 or
power-of-2 plus 1 (see f statement).

a, b, c, etc. -- ordinate values, in odd-numbered pfields p5, p7, p9, . . .

n1, n2, etc. -- length of segment (no. of storage locations), in
even-numbered pfields. Cannot be negative, but a zero is meaningful for
specifying discontinuous waveforms (e.g. in the example below). The sum
n1 + n2 + .... will normally equal size for fully specified functions.
If the sum is smaller, the function locations not included will be set
to zero; if the sum is greater, only the first size locations will be
stored.

  Note

  * If p4 is positive, functions are post-normalized (rescaled to a
    maximum absolute value of 1 after generation). A negative p4 will
    cause rescaling to be skipped.

  * Discrete-point linear interpolation implies an increase or decrease
    along a segment by equal differences between adjacent locations;
    exponential interpolation implies that the progression is by equal
    ratio. In both forms the interpolation from a to b is such as to
    assume that the value b will be attained in the n + 1th location.
    For discontinuous functions, and for the segment encompassing the
    end location, this value will not actually be reached, although it
    may eventually appear as a result of final scaling.


===========================================================================
GEN08                                                                 *GEN08*

  Description

This subroutine will generate a piecewise cubic spline curve, the
smoothest possible through all specified points.

  Syntax

f # time size 8 a n1 b n2 c n3 d ...

  Initialization

size -- number of points in the table. Must be a power of 2 or
power-of-2 plus 1 (see f statement).

a, b, c, etc. -- ordinate values of the function.

n1, n2, n3 ... -- length of each segment measured in stored values. May
not be zero, but may be fractional. A particular segment may or may not
actually store any values; stored values will be generated at integral
points from the beginning of the function. The sum n1 + n2 + ... will
normally equal size for fully specified functions.

  Note

  * GEN08 constructs a stored table from segments of cubic polynomial
    functions. Each segment runs between two specified points but
    depends as well on their neighbors on each side. Neighboring
    segments will agree in both value and slope at their common point.
    (The common slope is that of a parabola through that point and its
    two neighbors). The slope at the two ends of the function is
    constrained to be zero (flat).

  * Hint: to make a discontinuity in slope or value in the function as
    stored, arrange a series of points in the interval between two
    stored values; likewise for a non-zero boundary slope.


===========================================================================
GEN09                                                                 *GEN09*

  Description

These subroutines generate composite waveforms made up of weighted sums
of simple sinusoids. The specification of each contributing partial
requires 3 p-fields using GEN09.

  Syntax

f # time size 9 pna stra phsa pnb strb phsb ...

  Initialization

size -- number of points in the table. Must be a power of 2 or
power-of-2 plus 1 (see f statement).

pna, pnb, etc. -- partial no. (relative to a fundamental that would
occupy size locations per cycle) of sinusoid a, sinusoid b, etc. Must be
positive, but need not be a whole number, i.e., non-harmonic partials
are permitted. Partials may be in any order.

stra, strb, etc. -- strength of partials pna, pnb, etc. These are
relative strengths, since the composite waveform may be rescaled later.
Negative values are permitted and imply a 180 degree phase shift.

phsa, phsb, etc. -- initial phase of partials pna, pnb, etc., expressed
in degrees (0-360).

  Note

  * These subroutines generate stored functions as sums of sinusoids of
    different frequencies. The two major restrictions on GEN10 that the
    partials be harmonic and in phase do not apply to GEN09 or GEN19.

In each case the composite wave, once drawn, is then rescaled to
    unity if p4 was positive. A negative p4 will cause rescaling to be
    skipped.


===========================================================================
GEN10                                                                 *GEN10*

  Description

These subroutines generate composite waveforms made up of weighted sums
of simple sinusoids. The specification of each contributing partial
requires 1 pfield using GEN10.

  Syntax

f # time size 10 str1 str2 str3 str4 ...

  Initialization

size -- number of points in the table. Must be a power of 2 or
power-of-2 plus 1 (see f statement).

str1, str2, str3, etc. -- relative strengths of the fixed harmonic
partial numbers 1,2,3, etc., beginning in p5. Partials not required
should be given a strength of zero.

  Note

  * These subroutines generate stored functions as sums of sinusoids of
    different frequencies. The two major restrictions on GEN10 that the
    partials be harmonic and in phase do not apply to GEN09 or GEN19.

In each case the composite wave, once drawn, is then rescaled to
    unity if p4 was positive. A negative p4 will cause rescaling to be
    skipped.


===========================================================================
GEN11                                                                 *GEN11*

  Description

This subroutine generates an additive set of cosine partials, in the
manner of Csound generators buzz and gbuzz.

  Syntax

f # time size 11 nh [lh] [r]

  Initialization

size -- number of points in the table. Must be a power of 2 or
power-of-2 plus 1 (see f statement).

nh -- number of harmonics requested. Must be positive.

lh(optional) -- lowest harmonic partial present. Can be positive, zero
or negative. The set of partials can begin at any partial number and
proceeds upwards; if lh is negative, all partials below zero will
reflect in zero to produce positive partials without phase change (since
cosine is an even function), and will add constructively to any positive
partials in the set. The default value is 1

r(optional) -- multiplier in an amplitude coefficient series. This is a
power series: if the lhth partial has a strength coefficient of A the
(lh + n)th partial will have a coefficient of A * r^n , i.e. strength
values trace an exponential curve. r may be positive, zero or negative,
and is not restricted to integers. The default value is 1.

  Note

  * This subroutine is a non-time-varying version of the CSound buzzand
    gbuzz generators, and is similarly useful as a complex sound source
    in subtractive synthesis. With lh and r present it parallels gbuzz;
    with both absent or equal to 1 it reduces to the simpler buzz (i.e.
    nh equal-strength harmonic partials beginning with the fundamental).

  * Sampling the stored waveform with an oscillator is more efficient
    than using the dynamic buzz units. However, the spectral content is
    invariant and care is necessary, lest the higher partials exceed the
    Nyquist during sampling to produce fold-over.


===========================================================================
GEN12                                                                 *GEN12*

  Description

This generates the log of a modified Bessel function of the second kind,
order 0, suitable for use in amplitude-modulated FM.

  Syntax

f # time size 12 xint

  Initialization

size -- number of points in the table. Must be a power of 2 or a
power-of-2 plus 1 (see f statement). The normal value is power-of-2 plus 1.

xint -- specifies the x interval [0 to +xint] over which the function is
defined.

  Note

  * This subroutine draws the natural log of a modified Bessel function
    of the second kind, order 0 (commonly written as I subscript 0),
    over the x-interval requested. The call should have rescaling
    inhibited.

  * The function is useful as an amplitude scaling factor in
    cycle-synchronous amplitude-modulated FM. (See Palamin & Palamin, J.
    Audio Eng. Soc., 36/9, Sept. 1988, pp.671-684.) The algorithm is
    interesting because it permits the normally symmetric FM spectrum to
    be made asymmetric around a frequency other than the carrier, and is
    thereby useful for formant positioning. By using a table lookup
    index of I(r - 1/r), where I is the FM modulation index and r is an
    exponential parameter affecting partial strengths, the Palamin
    algorithm becomes relatively efficient, requiring only oscil's,
    table lookups, and a single exp call.


===========================================================================
GEN13                                                                 *GEN13*

  Description

Uses Chebyshev coefficients to generate stored polynomial functions
which, under waveshaping, can be used to split a sinusoid into harmonic
partials having a pre-definable spectrum.

  Syntax

f # time size 13 xint xamp h0 h1 h2 ...

  Initialization

size -- number of points in the table. Must be a power of 2 or a
power-of-2 plus 1 (see f statement). The normal value is power-of-2 plus 1.

xint -- provides the left and right values [-xint, +xint] of the x
interval over which the polynomial is to be drawn. These subroutines
both call GEN03 to draw their functions; the p5 value here is therefor
expanded to a negative-positive p5, p6 pair before GEN03 is actually
called. The normal value is 1.

xamp -- amplitude scaling factor of the sinusoid input that is expected
to produce the following spectrum.

h0, h1, h2, etc. -- relative strength of partials 0 (DC), 1
(fundamental), 2 ... that will result when a sinusoid of amplitude

xamp * int(size/2)/xint

is waveshaped using this function table. These values thus describe a
frequency spectrum associated with a particular factor xamp of the input
signal.

GEN13 is the function generator normally employed in standard
waveshaping. It stores a polynomial whose coefficients derive from the
Chebyshev polynomials of the first kind, so that a driving sinusoid of
strength xamp will exhibit the specified spectrum at output. Note that
the evolution of this spectrum is generally not linear with varying
xamp. However, it is bandlimited (the only partials to appear will be
those specified at generation time); and the partials will tend to occur
and to develop in ascending order (the lower partials dominating at low
xamp, and the spectral richness increasing for higher values of xamp). A
negative hn value implies a 180 degree phase shift of that partial; the
requested full-amplitude spectrum will not be affected by this shift,
although the evolution of several of its component partials may be. The
pattern +,+,-,-,+,+,... for h0,h1,h2... will minimize the normalization
problem for low xamp values (see above), but does not necessarily
provide the smoothest pattern of evolution.


===========================================================================
GEN14                                                                 *GEN14*

  Description

Uses Chebyshev coefficients to generate stored polynomial functions
which, under waveshaping, can be used to split a sinusoid into harmonic
partials having a pre-definable spectrum.

  Syntax

f # time size 14 xint xamp h0 h1 h2 ...

  Initialization

size -- number of points in the table. Must be a power of 2 or a
power-of-2 plus 1 (see f statement). The normal value is power-of-2 plus 1.

xint -- provides the left and right values [-xint, +xint] of the x
interval over which the polynomial is to be drawn. These subroutines
both call GEN03 to draw their functions; the p5 value here is therefore
expanded to a negative-positive p5, p6 pair before GEN03 is actually
called. The normal value is 1.

xamp -- amplitude scaling factor of the sinusoid input that is expected
to produce the following spectrum.

h0, h1, h2, etc. -- relative strength of partials 0 (DC), 1
(fundamental), 2 ... that will result when a sinusoid of amplitude

xamp * int(size/2)/xint

is waveshaped using this function table. These values thus describe a
frequency spectrum associated with a particular factor xamp of the input
signal.

  Note

  * GEN13 is the function generator normally employed in standard
    waveshaping. It stores a polynomial whose coefficients derive from
    the Chebyshev polynomials of the first kind, so that a driving
    sinusoid of strength xamp will exhibit the specified spectrum at
    output. Note that the evolution of this spectrum is generally not
    linear with varying xamp. However, it is bandlimited (the only
    partials to appear will be those specified at generation time); and
    the partials will tend to occur and to develop in ascending order
    (the lower partials dominating at low xamp, and the spectral
    richness increasing for higher values of xamp). A negative hn value
    implies a 180 degree phase shift of that partial; the requested
    full-amplitude spectrum will not be affected by this shift, although
    the evolution of several of its component partials may be. The
    pattern +,+,-,-,+,+,... for h0,h1,h2... will minimize the
    normalization problem for low xamp values (see above), but does not
    necessarily provide the smoothest pattern of evolution.

  * GEN14 stores a polynomial whose coefficients derive from Chebyshevs
    of the second kind.


===========================================================================
GEN15                                                                 *GEN15*

  Description

This subroutine creates two tables of stored polynomial functions,
suitable for use in phase quadrature operations.

  Syntax

f # time size 15 xint xamp h0 phs0 h1 phs1 h2 phs2 ...

  Initialization

size -- number of points in the table. Must be a power of 2 or a
power-of-2 plus 1 (see f statement). The normal value is power-of-2 plus 1.

xint -- provides the left and right values [-xint, +xint] of the x
interval over which the polynomial is to be drawn. This subroutine will
eventually call GEN03 to draw both functions; this p5 value is therefor
expanded to a negative-positive p5, p6 pair before GEN03 is actually
called. The normal value is 1.

xamp -- amplitude scaling factor of the sinusoid input that is expected
to produce the following spectrum.

h0, h1, h2, ... hn -- relative strength of partials 0 (DC), 1
(fundamental), 2 ... that will result when a sinusoid of amplitude

xamp * int(size/2)/xint

is waveshaped using this function table. These values thus describe a
frequency spectrum associated with a particular factor xamp of the input
signal.

phs0, phs1, ... -- phase in degrees of desired harmonics h0, h1, ...
when the two functions of GEN15 are used with phase quadrature.

  Notes

GEN15 creates two tables of equal size, labeled f # and f # + 1. Table #
will contain a Chebyshev function of the first kind, drawn using GEN13
with partial strengths h0cos(phs0), h1cos(phs1), ... Table #+1 will
contain a Chebyshev function of the 2nd kind by calling GEN14 with
partials h1sin(phs1), h2sin(phs2),... (note the harmonic displacement).
The two tables can be used in conjunction in a waveshaping network that
exploits phase quadrature.

Before version 5.16 there was a bug (pointed out by Menno Knevel and
fixed by François Pinot) on the number of pfields transmitted to gen13
and gen14 by gen15. The consequence is that all the csd, or orc and sco
files that used gen15 before this bug was fixed, are likely to sound
different now.


===========================================================================
GEN16                                                                 *GEN16*

  Description

Creates a table from beg value to end value of dur steps.

  Syntax

f # time size 16 val1 dur1 type1 val2 [dur2 type2 val3 ... typeX valN]

  Initialization

size -- number of points in the table. Must be a power of 2 or a
power-of-2 plus 1 (see f statement). The normal value is power-of-2 plus 1.

  Note
The end value is only reached when the table length is power-of-2 plus
1. (This length is crucial for use with the tab generator.)

beg -- starting value

dur -- number of segments

type -- if 0, a straight line is produced. If non-zero, then GEN16
creates the following curve, for dur steps:

beg + (end - beg) * (1 - exp( i*type/(dur-1) )) / (1 - exp(type))

end -- value after dur segments

Here are some examples of the curves generated for different values of
type:

Tables generated by GEN16 for different values of type.

Tables generated by GEN16 for different values of type.

  Note

If type > 0, there is a slowly rising (concave) or slowly decaying
(convex) curve, while if itype < 0, the curve is fast rising (convex) or
fast decaying (concave). See also transeg.

Example 1138. A simple example of the GEN16 routine.

<CsoundSynthesizer>
<CsOptions>
; Select audio/midi flags here according to platform
; Audio out   Audio in
-odac           -iadc    ;;;RT audio I/O
; For Non-realtime ouput leave only the line below:
; -o gen16.wav -W ;;; for file output any platform
</CsOptions>
<CsInstruments>

sr = 44100
ksmps = 128
nchnls = 1

instr 1
  kcps init 1/p3
  kndx phasor kcps

  ifn = p4
  ixmode = 1
  kval table kndx, ifn, ixmode

  ibasefreq = 440
  kfreq = kval * ibasefreq
  a1 oscil 20000, ibasefreq + kfreq, 1
  out a1
endin

</CsInstruments>
<CsScore>

f 1 0 16384 10 1

f 2 0 1024 16 1 1024 1 0
f 3 0 1024 16 1 1024 2 0
f 4 0 1024 16 1 1024 10 0
f 5 0 1024 16 1 1024 -1 0
f 6 0 1024 16 1 1024 -2 0
f 7 0 1024 16 1 1024 -10 0

i 1 0 2 2
i 1 + . 3
i 1 + . 4
i 1 + . 5
i 1 + . 6
i 1 + . 7

e

</CsScore>
</CsoundSynthesizer>


===========================================================================
GEN17                                                                 *GEN17*

  Description

This subroutine creates a step function from given x-y pairs.

  Syntax

f # time size 17 x1 a x2 b x3 c  ...

  Initialization

size -- number of points in the table. Must be a power of 2 or a
power-of-2 plus 1 (see f statement). The normal value is power-of-2 plus 1.

x1, x2, x3, etc. -- x-ordinate values, in ascending order, 0 first.

a, b, c, etc. -- y-values at those x-ordinates, held until the next
x-ordinate.

  Note

This subroutine creates a step function of x-y pairs whose y-values are
held to the right. The right-most y-value is then held to the end of the
table. The function is useful for mapping one set of data values onto
another, such as MIDI note numbers onto sampled sound ftable numbers (
see loscil).


===========================================================================
GEN18                                                                 *GEN18*

  Description

Writes composite waveforms made up of pre-existing waveforms. Each
contributing waveform requires 4 pfields and can overlap with other
waveforms.

  Syntax

f # time size 18 fna ampa starta finisha fnb ampb startb finishb ...

  Initialization

size -- number of points in the table. Must be a power-of-2 (see f
statement).

fna, fnb, etc. -- pre-existing table number to be written into the table.

ampa, ampb, etc. -- strength of wavefoms. These are relative strengths,
since the composite waveform may be rescaled later. Negative values are
permitted and imply a 180 degree phase shift.

starta, startb, etc. -- where to start writing the fn into the table.

finisha, finishb, etc. -- where to stop writing the fn into the table.
The last available location is the power of two - 1.


===========================================================================
GEN19                                                                 *GEN19*

  Description

These subroutines generate composite waveforms made up of weighted sums
of simple sinusoids. The specification of each contributing partial
requires 4 p-fields using GEN19.

  Syntax

f # time size  19  pna   stra  phsa  dcoa  pnb strb  phsb  dcob  ...

  Initialization

size -- number of points in the table. Must be a power of 2 or
power-of-2 plus 1 (see f statement).

pna, pnb, etc. -- partial no. (relative to a fundamental that would
occupy size locations per cycle) of sinusoid a, sinusoid b, etc. Must be
positive, but need not be a whole number, i.e., non-harmonic partials
are permitted. Partials may be in any order.

stra, strb, etc. -- strength of partials pna, pnb, etc. These are
relative strengths, since the composite waveform may be rescaled later.
Negative values are permitted and imply a 180 degree phase shift.

phsa, phsb, etc. -- initial phase of partials pna, pnb, etc., expressed
in degrees.

dcoa, dcob, etc. -- DC offset of partials pna, pnb, etc. This is applied
after strength scaling, i.e. a value of 2 will lift a 2-strength
sinusoid from range [-2,2] to range [0,4] (before later rescaling).

  Note

  * These subroutines generate stored functions as sums of sinusoids of
    different frequencies. The two major restrictions on GEN10 that the
    partials be harmonic and in phase do not apply to GEN09 or GEN19.

In each case the composite wave, once drawn, is then rescaled to
    unity if p4 was positive. A negative p4 will cause rescaling to be
    skipped.


===========================================================================
GEN20                                                                 *GEN20*

  Description

This subroutine generates functions of different windows. These windows
are usually used for spectrum analysis or for grain envelopes.

  Syntax

f # time size 20 window max [opt]

  Initialization

size -- number of points in the table. Must be a power of 2 ( + 1).

window -- Type of window to generate:

  * 1 = Hamming

  * 2 = Hanning

  * 3 = Bartlett ( triangle)

  * 4 = Blackman ( 3-term)

  * 5 = Blackman - Harris ( 4-term)

  * 6 = Gaussian

  * 7 = Kaiser

  * 8 = Rectangle

  * 9 = Sync

max -- For negative p4 this will be the absolute value at window peak
point. If p4 is positive or p4 is negative and p6 is missing the table
will be post-rescaled to a maximum value of 1.

opt -- Optional argument required by the Gaussian window and the Kaiser
window.


===========================================================================
GEN21                                                                 *GEN21*

  Description

This generates tables of different random distributions. (See also
betarand, bexprnd, cauchy, exprand, gauss, linrand, pcauchy, poisson,
trirand, unirand, and weibull)

  Syntax

f # time size 21 type level [arg1  [arg2]]

  Initialization

time and size are the usual GEN function arguments. level defines the
amplitude. Note that GEN21 is not self-normalizing as are most other GEN
functions. type defines the distribution to be used as follow:

  * 1 = Uniform (positive numbers only)

  * 2 = Linear (positive numbers only)

  * 3 = Triangular (positive and negative numbers)

  * 4 = Exponential (positive numbers only)

  * 5 = Biexponential (positive and negative numbers)

  * 6 = Gaussian (positive and negative numbers)

  * 7 = Cauchy (positive and negative numbers)

  * 8 = Positive Cauchy (positive numbers only)

  * 9 = Beta (positive numbers only)

  * 10 = Weibull (positive numbers only)

  * 11 = Poisson (positive numbers only)

Of all these cases only 9 (Beta) and 10 (Weibull) need extra arguments.
Beta needs two arguments and Weibull one.

If type = 6, the random numbers in the ftable follow a normal
distribution centered around 0.0 (mu = 0.0) with a variance (sigma) of
level / 3.83. Thus more than 99.99% of the random values generated are
in the range -level to +level. The default value for level is 1 (sigma =
0.261). If a mean value different of 0.0 is desired, this mean value has
to be added to the generated numbers.


===========================================================================
GEN23                                                                 *GEN23*

  Description

This subroutine reads numeric values from an external ASCII file.

  Syntax

f # time size -23 "filename.txt"

  Initialization

"filename.txt" -- numeric values contained in "filename.txt" (which
indicates the complete pathname of the character file to be read), can
be separated by spaces, tabs, newline characters or commas.

size -- number of points in the table. Must be a power of 2 , power of 2
+ 1, or zero. If size = 0, table size is determined by the number of
numeric values in filename.txt. (New in Csound version 3.57)

  Note

All characters following ';', '#' (comment) or '<' (XML tag from version
6.04) are ignored until next line (numbers too).


===========================================================================
GEN24                                                                 *GEN24*

  Description

This subroutine reads numeric values from another allocated
function-table and rescales them according to the max and min values
given by the user.

  Syntax

f # time size -24 ftable min max

  Initialization

#, time, size -- the usual GEN parameters. See f statement.

ftable -- ftable must be an already allocated table with the same size
as this function.

min, max -- the rescaling range.

  Note

This GEN is useful, for example, to eliminate the starting offset in
exponential segments allowing a real starting from zero.


===========================================================================
GEN25                                                                 *GEN25*

  Description

These subroutines are used to construct functions from segments of
exponential curves in breakpoint fashion.

  Syntax

f # time size 25 x1 y1 x2 y2 x3  ...

  Initialization

size -- number of points in the table. Must be a power of 2 or
power-of-2 plus 1 (see f statement).

x1, x2, x3, etc. -- locations in table at which to attain the following
y value. Must be in increasing order. If the last value is less than
size, then the rest will be set to zero. Should not be negative but can
be zero.

y1, y2, y3,, etc. -- Breakpoint values attained at the location
specified by the preceding x value. These must be non-zero and must be
alike in sign.

  Note

If p4 is positive, functions are post-normalized (rescaled to a maximum
absolute value of 1 after generation). A negative p4 will cause
rescaling to be skipped.


===========================================================================
GEN27                                                                 *GEN27*

  Description

Construct functions from segments of straight lines in breakpoint fashion.

  Syntax

f # time size 27 x1  y1 x2 y2 x3 ...

  Initialization

size -- number of points in the table. Must be a power of 2 or
power-of-2 plus 1 (see f statement).

x1, x2, x3, etc. -- locations in table at which to attain the following
y value. Must be in increasing order. If the last value is less than
size, then the rest will be set to zero. Should not be negative but can
be zero.

y1, y2, y3,, etc. -- Breakpoint values attained at the location
specified by the preceding x value.

  Note

If p4 is positive, functions are post-normalized (rescaled to a maximum
absolute value of 1 after generation). A negative p4 will cause
rescaling to be skipped.


===========================================================================
GEN28                                                                 *GEN28*

  Description

This function generator reads a text file which contains sets of three
values representing the xy coordinates and a time-tag for when the
signal should be placed at that location, allowing the user to define a
time-tagged trajectory. The file format is in the form:

time1    X1      Y1
time2    X2      Y2
time3    X3      Y3

The configuration of the xy coordinates in space places the signal in
the following way:

  * a1 is -1, 1

  * a2 is 1, 1

  * a3 is -1, -1

  * a4 is 1, -1

This assumes a loudspeaker set up as a1 is left front, a2 is right
front, a3 is left back, a4 is right back. Values greater than 1 will
result in sounds being attenuated as if in the distance. GEN28 creates
values to 10 milliseconds of resolution.

  Syntax

f # time size 28 ifilcod

  Initialization

size -- number of points in the table. Must be 0. GEN28 takes 0 as the
size and automatically allocates memory.

ifilcod -- character-string denoting the source file name. A
character-string (in double quotes, spaces permitted) gives the filename
itself, optionally a full pathname. If not a full path, the named file
is sought in the current directory.


===========================================================================
GEN30                                                                 *GEN30*

  Description

Extracts a range of harmonic partials from an existing waveform.

  Syntax

f # time size  30  src  minh maxh [ref_sr] [interp]

  Performance

src -- source ftable

minh -- lowest harmonic number

maxh -- highest harmonic number

ref_sr (optional) -- maxh is scaled by (sr / ref_sr). The default value
of ref_sr is sr. If ref_sr is zero or negative, it is now ignored.

interp (optional) -- if non-zero, allows changing the amplitude of the
lowest and highest harmonic partial depending on the fractional part of
minh and maxh. For example, if maxh is 11.3 then the 12th harmonic
partial is added with 0.3 amplitude. This parameter is zero by default.

GEN30 does not support tables with an extended guard point (ie. table
size = power of two + 1). Although such tables will work both for input
and output, when reading source table(s), the guard point is ignored,
and when writing the output table, guard point is simply copied from the
first sample (table index = 0).

The reason of this limitation is that GEN30 uses FFT, which requires
power of two table size. GEN32 allows using linear interpolation for
resampling and phase shifting, which makes it possible to use any table
size (however, for partials calculated with FFT, the power of two
limitation still exists).


===========================================================================
GEN31                                                                 *GEN31*

  Description

This routine is similar to GEN09, but allows mixing any waveform
specified in an existing table.

  Syntax

f # time size  31  src  pna stra phsa  pnb strb phsb  ...

  Performance

src -- source table number

pna, pnb, ... -- partial number, must be a positive integer

stra, strb, ... -- amplitude scale

phsa, phsb, ... -- start phase (0 to 1)

GEN31 does not support tables with an extended guard point (ie. table
size = power of two + 1). Although such tables will work both for input
and output, when reading source table(s), the guard point is ignored,
and when writing the output table, guard point is simply copied from the
first sample (table index = 0).

The reason of this limitation is that GEN31 uses FFT, which requires
power of two table size. GEN32 allows using linear interpolation for
resampling and phase shifting, which makes it possible to use any table
size (however, for partials calculated with FFT, the power of two
limitation still exists).


===========================================================================
GEN32                                                                 *GEN32*

  Description

This routine is similar to GEN31, but allows specifying source ftable
for each partial. Tables can be resampled either with FFT, or linear
interpolation.

  Syntax

f # time size  32  srca  pna stra phsa  srcb pnb strb phsb  ...

  Performance

srca, srcb -- source table number. A negative value can be used to read
the table with linear interpolation (by default, the source waveform is
transposed and phase shifted using FFT); this is less accurate, but
faster, and allows non-integer and negative partial numbers.

pna, pnb, ... -- partial number, must be a positive integer if source
table number is positive (i.e. resample with FFT).

stra, strb, ... -- amplitude scale

phsa, phsb, ... -- start phase (0 to 1)


===========================================================================
GEN33                                                                 *GEN33*

  Description

These routines generate composite waveforms by mixing simple sinusoids,
similarly to GEN09, but the parameters of the partials are specified in
an already existing table, which makes it possible to calculate any
number of partials in the orchestra.

The difference between GEN33 and GEN34 is that GEN33 uses inverse FFT to
generate output, while GEN34 is based on the algorithm used in oscils
opcode. GEN33 allows integer partials only, and does not support power
of two plus 1 table size, but may be significantly faster with a large
number of partials. On the other hand, with GEN34, it is possible to use
non-integer partial numbers and extended guard point, and this routine
may be faster if there is only a small number of partials (note that
GEN34 is also several times faster than GEN09, although the latter may
be more accurate).

  Syntax

f # time size  33  src nh scl [fmode]

  Initialization

size -- number of points in the table. Must be power of two and at least 4.

src -- source table number. This table contains the parameters of each
partial in the following format:

stra, pna, phsa, strb, pnb, phsb, ...

the parameters are:

  * stra, strb, etc.: relative strength of partials. The actual
    amplitude depends on the value of scl, or normalization (if enabled).

  * pna, pnb, etc.: partial number, or frequency, depending on fmode
    (see below); zero and negative values are allowed, however, if the
    absolute value of the partial number exceeds (size / 2), the partial
    will not be rendered. With GEN33, partial number is rounded to the
    nearest integer.

  * phsa, phsb, etc.: initial phase, in the range 0 to 1.

Table length (not including the guard point) should be at least 3 * nh.
If the table is too short, the number of partials (nh) is reduced to
(table length) / 3, rounded towards zero.

nh -- number of partials. Zero or negative values are allowed, and
result in an empty table (silence). The actual number may be reduced if
the source table (src) is too short, or some partials have too high
frequency.

scl -- amplitude scale.

fmode (optional, default = 0) -- a non-zero value can be used to set
frequency in Hz instead of partial numbers in the source table. The
sample rate is assumed to be fmode if it is positive, or -(sr * fmode)
if any negative value is specified.


===========================================================================
GEN34                                                                 *GEN34*

  Description

These routines generate composite waveforms by mixing simple sinusoids,
similarly to GEN09, but the parameters of the partials are specified in
an already existing table, which makes it possible to calculate any
number of partials in the orchestra.

The difference between GEN33 and GEN34 is that GEN33 uses inverse FFT to
generate output, while GEN34 is based on the algorithm used in oscils
opcode. GEN33 allows integer partials only, and does not support power
of two plus 1 table size, but may be significantly faster with a large
number of partials. On the other hand, with GEN34, it is possible to use
non-integer partial numbers and extended guard point, and this routine
may be faster if there is only a small number of partials (note that
GEN34 is also several times faster than GEN09, although the latter may
be more accurate).

  Syntax

f # time size  34  src nh scl [fmode]

  Initialization

size -- number of points in the table. Must be power of two or a power
of two plus 1.

src -- source table number. This table contains the parameters of each
partial in the following format:

stra, pna, phsa, strb, pnb, phsb, ...

the parameters are:

  * stra, strb, etc.: relative strength of partials. The actual
    amplitude depends on the value of scl, or normalization (if enabled).

  * pna, pnb, etc.: partial number, or frequency, depending on fmode
    (see below); zero and negative values are allowed, however, if the
    absolute value of the partial number exceeds (size / 2), the partial
    will not be rendered.

  * phsa, phsb, etc.: initial phase, in the range 0 to 1.

Table length (not including the guard point) should be at least 3 * nh.
If the table is too short, the number of partials (nh) is reduced to
(table length) / 3, rounded towards zero.

nh -- number of partials. Zero or negative values are allowed, and
result in an empty table (silence). The actual number may be reduced if
the source table (src) is too short, or some partials have too high
frequency.

scl -- amplitude scale.

fmode (optional, default = 0) -- a non-zero value can be used to set
frequency in Hz instead of partial numbers in the source table. The
sample rate is assumed to be fmode if it is positive, or -(sr * fmode)
if any negative value is specified.


===========================================================================
GEN40                                                                 *GEN40*

  Description

Generates a continuous random distribution function starting from the
shape of a user-defined distribution histogram.

  Syntax

f # time size 40 shapetab

  Performance

The shape of histogram must be stored in a previously defined table, in
fact shapetab argument must be filled with the number of such table.

Histogram shape can be generated with any other GEN routines. Since no
interpolation is used when GEN40 processes the translation, it is
suggested that the size of the table containing the histogram shape to
be reasonably big, in order to obtain more precision (however after the
processing the shaping-table can be destroyed in order to re-gain memory).

This subroutine is designed to be used together with cuserrnd opcode
(see cuserrnd for more information).


===========================================================================
GEN41                                                                 *GEN41*

  Description

Generates a discrete random distribution function by giving a list of
numerical pairs.

  Syntax

f # time size -41 value1 prob1 value2 prob2 value3 prob3 ... valueN probN 

  Performance

The first number of each pair is a value, and the second is the
probability of that value to be chosen by a random algorithm. Even if
any number can be assigned to the probability element of each pair, it
is suggested to give it a percent value, in order to make it clearer for
the user.

This subroutine is designed to be used together with duserrnd and urd
opcodes (see duserrnd for more information).


===========================================================================
GEN42                                                                 *GEN42*

  Description

Generates a random distribution function of discrete ranges of values by
giving a list of groups of three numbers.

  Syntax

f # time size -42  min1 max1 prob1 min2 max2 prob2 min3 max3 prob3 ...  minN maxN probN

  Performance

The first number of each group is a the minimum value of the range, the
second is the maximum value and the third is the probability of that an
element belonging to that range of values can be chosen by a random
algorithm. Probabilities for a range should be a fraction of 1, and the
sum of the probabilities for all the ranges should total 1.0.

This subroutine is designed to be used together with duserrnd and urd
opcodes (see duserrnd for more information). Since both duserrnd and urd
do not use any interpolation, it is suggested to give a size reasonably
big.


===========================================================================
GEN43                                                                 *GEN43*

  Description

This subroutine loads a PVOCEX file containing the PV analysis
(amp-freq) of a soundfile and calculates the average magnitudes of all
analysis frames of one or all audio channels. It then creates a table
with these magnitudes for each PV bin.

  Syntax

f # time size 43 filecod channel

  Initialisation

size -- number of points in the table, power-of-two or power-of-two plus
1. GEN 43 does not make any distinction between these two sizes, but it
requires the table to be at least the fftsize/2. PV bins cover the
positive spectrum from 0Hz (table index 0) to the Nyquist (table index
fftsize/2+1) in equal-size frequency increments (of size sr/fftsize).

filcod -- a pvocex file (which can be generated by pvanal).

channel -- audio channel number from which the magnitudes will be
extracted; a 0 will average the magnitudes from all channels.

Reading stops at the end of the file.

  Note

if p4 is positive, the table will be post-normalised. A negative p4 will
cause post-normalisation to be skipped.


===========================================================================
GEN49                                                                 *GEN49*

  Description

This subroutine transfers data from an MP3 soundfile into a function table.

  Syntax

f#  time  size  49  filcod  skiptime  format

  Performance

size -- number of points in the table. Ordinarily a power of 2 or a
power-of-2 plus 1 (see f statement); the maximum tablesize is 16777216
(2^24 ) points. The allocation of table memory can be deferred by
setting this parameter to 0; the size allocated is then the number of
points in the file (probably not a power-of-2), and the table is not
usable by normal oscillators, but it is usable by a loscil unit. The
soundfile can also be mono or stereo.

filcod -- integer or character-string denoting the source soundfile
name. An integer denotes the file soundin.filcod ; a character-string
(in double quotes, spaces permitted) gives the filename itself,
optionally a full pathname. If not a full path, the file is sought first
in the current directory, then in that given by the environment variable
SSDIR (if defined) then by SFDIR. See also soundin.

skiptime -- begin reading at skiptime seconds into the file.

format -- specifies the audio data-file format required:

1 - Mono file                 3 - First channel (left)
2 - Stereo file               4 - Second channel (right)

If format = 0 the sample format is taken from the soundfile header.

  Note

  * Reading stops at end-of-file or when the table is full. Table
    locations not filled will contain zeros.

  * If p4 is positive, the table will be post-normalized (rescaled to a
    maximum absolute value of 1 after generation). A negative p4 will
    cause rescaling to be skipped.


===========================================================================
GEN51                                                                 *GEN51*

  Description

This subroutine fills a table with a fully customized micro-tuning
scale, in the manner of Csound opcodes cpstun, cpstuni et cpstmid.

  Syntax

f # time size -51 numgrades interval basefreq basekey tuningRatio1 tuningRatio2  .... tuningRationN

  Performance

The first four parameters (i.e. p5, p6, p7 and p8) define the following
generation directives:

p5 (numgrades) -- the number of grades of the micro-tuning scale

p6 (interval) -- the frequency range covered before repeating the grade
ratios, for example 2 for one octave, 1.5 for a fifth etcetera

p7 (basefreq) -- the base frequency of the scale in cps

p8 (basekey) -- the integer index of the scale to which to assign
basefreq unmodified

The other parameters define the ratios of the scale:

p9...pN (tuningRatio1...etc.) -- the tuning ratios of the scale

For example, for a standard 12-grade scale with the base-frequency of
261 cps assigned to the key-number 60, the corresponding f-statement in
the score to generate the table should be:

;             numgrades        basefreq           tuning-ratios  (eq.temp) .......
;                     interval         basekey
f1 0 64 -51     12       2      261      60        1   1.059463 1.12246 1.18920 ..etc...

After the gen has been processed, the table f1 is filled with 64
different frequency values. The 60th element is filled with the
frequency value of 261, and all other elements (preceding and
subsequents) of the table are filled according to the tuning ratios

Another example with a 24-grade scale with a base frequency of 440
assigned to the key-number 48, and a repetition interval of 1.5:

;            numgrades       basefreq             tuning-ratios .....
;                     interval         basekey
f1 0 64 -51     24      1.5     440      48         1   1.01  1.02  1.03  ..etc...


===========================================================================
GEN52                                                                 *GEN52*

  Description

GEN52 creates an interleaved multichannel table from the specified
source tables, in the format expected by the ftconv opcode. It can also
be used to extract a channel from a multichannel table and store it in a
normal mono table, copy tables with skipping some samples, adding delay,
or store in reverse order, etc.

Three parameters must be given for each channel to be processed. fsrc
declares the source f-table number. The parameter offset specifies an
offset for the source file. If different to 0, the source file is not
read from the beginning, but the offset number of values are skipped.
The offset is used to determine the channel number to be read from
interleaved f-tables, e.g. for channel 2, offset must be 1. It can also
be used to set a read offset on the source table. This parameter gives
absolute values, so if a skip of 20 sample frames for a 2 channel
f-table is desired, offset must be set to 40. The srcchnls parameter is
used to declare the number of channels in the source f-table. This
parameter sets the skip size when reading the source f-table.

When more than one channel (nchannels > 1) is given, source f-tables are
interleaved in the newly created table.

If the source f-table is finished before the destination f-table is
full, the remaining values are set to 0.

  Syntax

f # time size 52 nchannels fsrc1 offset1 srcchnls1 [fsrc2 offset2 srcchnls2 ... fsrcN offsetN srcchnlsN]


===========================================================================
GENtanh                                                             *GENtanh*

  Description

Creates an ftable with values of the tanh function.

  Syntax

f # time size "tanh" start end rescale

  Initialization

size -- number of points in the table. Must be a power of 2 or
power-of-2 plus 1 (see f statement).

start, end -- first and last value to be stored; the GEN draws a curve
that goes from start to end: tanh(start) .... tanh(end). The points
stored are uniformly spaced between these to the table size

rescale -- if not zero the table is not rescaled


===========================================================================
GENexp                                                               *GENexp*

  Description

Creates an ftable with values of the exp function.

  Syntax

f # time size "exp" start end rescale

  Initialization

size -- number of points in the table. Must be a power of 2 or
power-of-2 plus 1 (see f statement).

start, end -- first and last value to be stored; the GEN draws a curve
that goes from start to end: exp(start) .... exp(end). The points stored
are uniformly spaced between these to the table size

rescale -- if not zero the table is not rescaled


===========================================================================
GENsone                                                             *GENsone*

  Description

Creates an ftable with values of the sone function for equal power.

  Syntax

f # time size "sone" start end equalpoint rescale

  Initialization

size -- number of points in the table. Must be a power of 2 or
power-of-2 plus 1 (see f statement).

start, end -- first and last value to be stored. The points stored are
uniformly spaced between these to the table size.

equalpoint -- the point on the curve when the input and output values
are equal.

rescale -- if not zero the table is not rescaled

The table is filled with the function x*POWER(x/eqlp, FL(33.0)/FL(78.0))
for x between the start and end points. This is the Sone loudness curve.


===========================================================================
GENfarey                                                           *GENfarey*

  Description

A Farey Sequence F_n of order n is a list of fractions in their lowest
terms between 0 and 1 and in ascending order. Their denominators do not
exceed n. This means a fraction a/b belongs to F_n if 0 ≤ a ≤ b ≤ n. The
numerator and denominator of each fraction are always coprime. 0 and 1
are included in F_n as the fractions 0/1 and 1/1. For example F_5 =
{0/1, 1/5, 1/4, 1/3, 2/5, 1/2, 3/5, 2/3, 3/4, 4/5, 1/1} Some properties
of the Farey Sequence:

  * If a/b and c/d are two successive terms of F_n , then bc - ad = 1.
  * If a/b, c/d, e/f are three successive terms of F_n , then: c/d =
    (a+e) / (b+f). In this case c/d is called the mediant fraction
    between a/b and e/f.
  * If n > 1, then no two successive terms ofF_n have the same denominator. 

The length of any Farey Sequence F_n is determined by |F_n | = 1 + SUM
over n (phi(m)) where phi(m) is Euler's totient function, which gives
the number of integers ≤ m that are coprime to m.

Some values for the length of F_n given n:

n       F_n
1       2
2       3
3       5
4       7
5       11
6       13
7       19
8       23
9       29
10      33
11      43
12      47
13      59
14      65
15      73
16      81
17      97
18      103
19      121
20      129

  Syntax

f # time size "farey" fareynum mode

  Initialization

size -- number of points in the table. Must be a power of 2 or
power-of-2 plus 1 (see f statement).

fareynum -- the integer n for generating Farey Sequence F_n

mode -- integer to trigger a specific output to be written into the table:

  * 0 -- outputs floating point numbers representing the elements of F_n .

  * 1 -- outputs delta values of successive elements of F_n , useful for
    generating note durations for example.

  * 2 -- outputs only the denominators of the integer ratios, useful for
    indexing other tables or instruments for example.

  * 3 -- same as mode 2 but with normalised output.

  * 4 -- same as mode 0 but with 1 added to each number, useful for
    generating tables for tuning opcodes, for example cps2pch.


===========================================================================
GENwave                                                             *GENwave*

  Description

Creates a compactly supported wavelet, scaling function or wavelet
packet. The output function is obtained by deconvolution of
corresponding mirror filter impulse response. This procedure is applied
in an iterative fashion.

The filter bank used in classic discrete wavelet transform grows only
towards low frequencies. Meanwhile wavelet packet transform introduces
any possible direction of tree's growth. The sequence of mirror filters
used in deconvolution is determined by binary form of seq value. "0"
corresponds to low-pass filter and "1" to high-pass.

The number of iteration steps is determined by filter's length and size
of function table. I.e. for filter length 8 and table size 256 there are
log2(256/8) = 5 iterations available.

  Syntax

f # time size "wave" fnsf seq rescale

  Initialization

size -- number of points in the table. Must be a power of 2 or
power-of-2 plus 1 (see f statement).

fnsf -- pre-existing table with scaling function coefficients.

seq -- non-negative integer number which corresponds to sequence of
low-pass and high-pass mirror filters during deconvolution procedure.

rescale -- if not zero the table is not rescaled


===========================================================================
GENpadsynth                                                     *GENpadsynth*

  Description

Paul Octavian Nasca's "padsynth algorithm" adds bandwidth to each
partial of a periodic weaveform. This bandwidth is heard as color,
movement, and additional richness of sound.

First, the waveform is defined by the user as a series of harmonic
partials. Then, bandwidth is added by independently spreading each
partial of the original waveform from a single frequency across
neighboring frequencies, according to a "profile" function: a Gaussian
curve, a square, or a rising and then falling expontential.

The partials of the original waveform may be considered to be samples in
a discrete Fourier transform of the waveform. Normally there is not an
exact one-to-one correspondence between the frequencies of the samples
(frequency bins) of the discrete Fourier transform with the frequencies
of the partials of the original waveform, because any frequency in the
inverse of the discrete Fourier transform might be synthesized by
interference between any number of bins. However, the padsynth algorithm
uses a simple trick to create this correspondence. The discrete Fourier
transform is simply made so large that the frequency of any partial of
the original waveform will be very close to the frequency of the
corresponding bin in the Fourier transform. Once this correspondence has
been created, the bandwidth profile can be applied by centering it over
the frequency bin of the original partial, scaling the profile by the
bandwidth, and simply multiplying the original partial by each sample of
the profile and adding the product to the corresponding bin of the
Fourier transform.

As the frequencies of the partials increase, their bandwidth may
optionally become wider or (less often) narrower.

Once each partial has been spread out in this way, the discrete Fourier
transform may be given random phases, and is then simply inverted to
synthesize the desired waveform, which may be used as the wavetable for
a digital oscillator.

N.B.: The size of the function table does NOT necessarily reflect one
periodic cycle of the waveform that it contains. The fundamental
frequency must be used to generate the desired pitch from an oscillator
using the function table, e.g.

|oscillator_hz = desired_hz * (sr / padsynth_size / fundamental_hz) |

  Syntax

f # score_time table_size "padsynth" fundamental_frequency
    partial_bandwidth partial_scale harmonic_stretch profile_shape profile_shape_parameter
    partial1_amplitude [partial2_amplitude ...]

  Initialization

table_size -- Function table size. Should be large, e.g. 2^18 == 262144.
Must be a power of 2 or power-of-2 plus 1 (see f statement).

fundamental_frequency -- Fundamental frequency for the generated table.

partial_bandwidth -- Bandwidth of each partial in cents.

partial_scale -- Scaling factor for bandwidth of each partial (log of
increase/decrease with partial frequency, 0 is no stretch or shrink).

harmonic_stretch -- Harmonic stretch/shrink for all partials (1 is
harmonic).

profile_shape -- Number specifying the shape of the bandwidth profile: 1
= Gaussian, 2 = square, and 3 = exponential

profile_shape_parameter -- Parameter passed to the function generating
the profile shape, e.g. exponent.

partial1_amplitude, partial2_amplitude, ... -- Amplitudes for each
partial (may be zero).


 vim:tw=78:ts=8:ft=help:norl:
