Content
CONTENTS

SYNTAX OF THE ORCHESTRA

CONSTANTS AND VARIABLES

VALUE CONVERTERS:  int, frac, abs, ftlen, i,

 	exp, log, sqrt, sin, cos, dbamp, ampdb

PITCH CONVERTERS:  octpch, pchoct,cpspch, octcps, cpsoct

ARITHMETIC OPERATIONS

CONDITIONAL VALUES

EXPRESSIONS

ASSIGNMENT STATEMENTS:  =, init, tival, divz

ORCHESTRA HEADER:  sr, kr, ksmps, nchnls

INSTRUMENT BLOCKS: instr, endin

PROGRAM CONTROL: goto, tigoto, if ... goto, timout

REINITIALIZATION: reinit, rigoto, rireturn

DURATIONAL CONTROL: ihold, turnoff

MIDI CONVERTERS:  notnum, veloc, cpsmidi(b), octmidi(b),

 pchmidi(b), ampmidi, aftouch, chpress, pchbend, midictrl

SIGNAL GENERATORS:

line, expon, linseg, expseg

phasor

table, tablei, oscil1, oscil1i

oscil, oscili, foscil, foscili

loscil

buzz, gbuzz

adsyn, pvoc

fof

pluck

rand, randh, randi

grain

xlinrand, xtrirand, xexprand, xbexprnd, xcauchy, xpcauchy, xpoisson, xgauss, xweibull, xbeta

SIGNAL MODIFIERS:

linen, linenr, envlpx

port, tone, atone, reson, areson

lpread, lpreson, lpfreson

rms, gain, balance

downsamp, upsamp, interp, integ, diff, samphold

delayr, delayw, delay, delay1

deltap, deltapi

comb, alpass, reverb

buttherhp,gutterlp,butterbp,butterbr

vdelay

multitap

reverb2

follow

power

convolve

OPERATIONS WITH SPECTRAL DATA TYPES:

octdown, noctdft

specaddm, specdiff, specscal, spechist, specfilt

specptrk, specsum, specdisp

SENSING & CONTROL:

tempest

xyin, tempo

SIGNAL INPUT & OUTPUT:

in, ins, insq, soundin, out, outs, outq

pan

kdump, kdump2, kdump3, kdump4

SIGNAL DISPLAY:

print, display, dispfft

STANDARD NUMERIC SCORE

Preprocessing of Standard Scores

Next-P and Previous-P Symbols

Ramping

Function Table Statement

Instrument Note Statements

Advance Statement

Tempo Statement

Sections of Score

       	End of Score

GEN ROUTINES

GEN01

GEN02

GEN03

GEN04

GEN05, GEN07

GEN06

GEN08

GEN09, GEN10, GEN19

GEN11

GEN12

GEN13, GEN14

GEN15

GEN17

GEN20

GEN21


Constants & Variables
CONSTANTS AND VARIABLES

constants are floating point numbers, such as 1, 3.14159, or -73.45.  They are available continuously and do not change in value.

variables are named cells containing numbers.  They are available continuously and may be updated at one of the four update rates (setup only, I-rate, K-rate, or A-rate).  I- and K-rate variables are scalars (i.e.  they take on only one value at any given time) and are primarily used to store and recall controlling data, that is, data that changes at the note rate (for I-variables) or at the control rate (for K-variables).  I- and K-variables are therefore useful for storing note parameter values, pitches, durations, slow-moving frequencies, vibratos, etc.  A-variables, on the other hand, are arrays or vectors of information.  Though renewed on the same perf-time control pass as K-variables, these array cells represent a finer resolution of time by dividing the control period into sample periods (see ksmps below).  A-variables are used to store and recall data changing at the audio sampling rate (e.g.  output signals of oscillators, filters, etc.).

A further distinction is that between local and global variables.  local variables are private to a particular instrument, and cannot be read from or written into by any other instrument.  Their values are preserved, and they may carry information from pass to pass (e.g.  from initialization time to performance time) within a single instrument.  Local variable names begin with the letter p, i, k, or a.  The same local variable name may appear in two or more different instrument blocks without conflict.

global variables are cells that are accessible by all instruments.  The names are either like local names preceded by the letter g, or are special reserved symbols.  Global variables are used for broadcasting general values, for communicating between instruments (semaphores), or for sending sound from one instrument to another (e.g. mixing prior to reverberation).

Given these distinctions, there are eight forms of local and global variables:

type	when renewable	Local	Global

reserved symbols	permanent	--	rsymbol

score parameter fields	I-time	pnumber	--

init variables	I-time	iname	giname

control signals	P-time, K-rate	kname	gkname

audio signals	P-time, A-rate 	aname	ganame

where rsymbol is a special reserved symbol (e.g.  sr, kr), number is a positive integer referring to a score statement pfield, and name is a string of letters and/or digits with local or global meaning.  As might be inferred, score parameters are local I-variables whose values are copied from the invoking score statement just prior to the Init pass through an instrument.


VALUE CONVERTERS

ftlen(x)	(init-rate args only)

int(x)	(init- or control-rate args only)

frac(x)	(init- or control-rate args only)

dbamp(x)	(init- or control-rate args only)

i(x)	(control-rate args only)

abs(x)	(no rate restriction)

exp(x)	(no rate restriction)

log(x)	(no rate restriction)

sqrt(x)	(no rate restriction)

sin(x)	(no rate restriction)

cos(x)	(no rate restriction)

ampdb(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.

ftlen(x)	returns the size (no.  of points) of stored function table no.  x.

int(x)	returns the integer part of x.

frac(x)	returns the fractional part of x.

dbamp(x)	returns the decibel equivalent of the raw amplitude x.

i(x)	returns an Init-type equivalent of the argument, thus permitting a K-time value to be

accessed in at init-time or reinit-time, whenever valid.

abs(x)	returns the absolute value of x.

exp(x)	returns e  raised to the xth power.

log(x)	returns the natural log of x (x positive only).

sqrt(x)	returns the square root of x  (x non-negative).

sin(x)	returns the sine of x (x in radians).

cos(x)	returns the cosine of x (x in radians).

ampdb(x)	returns the amplitude equivalent of the decibel value x.

Thus 60 db gives 1000, 66 db gives 2000, 72 db gives 4000,

78 db gives 8000, 84 db gives 16000 and 90 db gives 32000.

Note that for log, sqrt, and ftlen the argument value is restricted.  Note also that ftlen will always return a power-of-2 value, i.e. the function table guard point (see F statement) is not included.


PITCH CONVERTERS

octpch(pch)	(init- or control-rate args only)

pchoct(oct) 	(init- or control-rate args only)

cpspch(pch) 	(init- or control-rate args only)

octcps(cps) 	(init- or control-rate args only)

cpsoct(oct)	(no rate restriction)

where the argument within the parentheses may be a further expression.

These 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:

name	abbreviation

octave point pitch-class (8ve.pc)	pch

octave point decimal	oct

cycles per second 	cps

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.  Thus A440 can be represented alternatively by 440 (cps),8.09 (pch), 8.75 (oct), or 7.21 (pch), etc.  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 will repeat the calculation every, K-period since that is the rate at which K1 varies.

N.B.	The conversion from pch or oct 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.


Arithmetic Operations
ARITHMETIC OPERATIONS:

 - a

+ a

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

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

a +  b

a  -  b

a  * b

a  /  b

where the arguments a and b may be further expressions.

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.


Conditional Values
CONDITIONAL VALUES:

(a > b 	?  v1 : v2)

(a < b	?  v1 : v2)

(a  > = b   ?  v1 : v2)

(a  < = b   ?  v1 : v2)

(a  = = b   ?  v1 : v2)

(a  ! = b   ?  v1 : v2)

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

In the above conditionals, a and b are first compared.  If the indicated relation is true (a  greater than b, a less than b, a greater than or equal to b, a less than or equal to b, a equal to b, 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.  (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 | | ).

Example:

(k1 < p5/2 + p6 ? k1 : p7)

binds the terms p5/2 and p6.  It will return the value k1 below this threshold, else the value p7.


Expressions
EXPRESSIONS:

Expressions may be composed to any depth from the components shown above.  Each part of an expression is evaluated at its own proper rate.  For instance, if the terms within a sub-expression all change at the control rate or slower, the sub-expression will be evaluated only at the control rate; that result might then be used in an audio-rate evaluation.  For example, in

k1 + abs(int(p5) + frac(p5) * 100/12 +  sqrt(k1))

the 100/12 would be evaluated at orch init, the p5 expressions evaluated at note I-time, and the remainder of the expression evaluated every k-period.  The whole might occur in a unit generator argument position, or be part of an assignment statement .


ASSIGNMENT STATEMENTS

ir	=	iarg

kr	=	karg

ar	=	xarg

kr	init	iarg

ar	init	iarg

ir 	tival

ir	divz	ia, ib, isubst   (these not yet implemented)

kr	divz	ka, kb, ksubst

ar	divz	xa, xb, ksubst

= (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.

init - Put the value of the I-time expression iarg into a K- or A-variable, i.e., initialize the result.  Note that init provides the only case of an Init-time statement being permitted to write into a Perftime (K- or A-rate) result cell; the statement has no effect at Perf-time.

tival - Put the value of the instrument's internal "tie-in" flag into the named I-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.)

divz  - 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.

Example:

kcps	  =	i2/3 + cpsoct(k2 + octpch(p5))


Orchestra Header
ORCHESTRA HEADER STATEMENTS

sr = n1

kr = n2

ksmps = n3

nchnls = n4

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.

sr = (optional) - set sampling rate to n1 samples per second per channel.  The default value is 10000.

kr = (optional) - set control rate to n2 samples per second.  The default value is 1000.

ksmps = (optional) - set the number of samples in a Control Period to n3.  This value must equal sr/kr.  The default value is 10.

nchnls = (optional) - set number of channels of audio output to n4.  (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.

Example of header assignments:

sr = 10000

kr = 500

ksmps = 20

gi1	=	sr/2.

ga	init	0

gitranspose =	octpch(.0l)


instrument_blocks
INSTRUMENT BLOCK STATEMENTS

instr	    i, j, ...

.

.	< body

.	   of

.	   instrument >

.

endin

These statements delimit an instrument block.  They must always occur in pairs.

instr - begin 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.

endin - end the current instrument block.

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).

Instrument blocks cannot be nested (i.e. one block cannot contain another).


Program Control
PROGRAM CONTROL STATEMENTS

igoto	label

tigoto	label

kgoto	label

goto	label

if	ia R ib igoto label

if	ka R kb kgoto label

if	ia R ib goto label

timout 	istrt, idur, label

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).

These statements are used to control the order in which statements in an instrument block are to be executed.  I-time and P-time passes can be controlled separately as follows:

igoto - During the I-time pass only, unconditionally transfer control to the statement labeled by label.

tigoto - 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); no-op 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, delay).

kgoto - During the P-time passes only, unconditionally transfer control to the statement labeled by label.

goto - (combination of igoto and kgoto) Transfer control to label on every pass.

if...igoto - conditional branch at I-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 P-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.

timout - 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 next page).

Example:

if k3 > p5 + 10 kgoto next


Reinitialization
REINITIALIZATION STATEMENTS:

reinit	label

rigoto	label

rireturn

These statements permit an instrument to reinitialize itself during performance.

reinit - 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.

rigoto - 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.

rireturn - terminates a reinit pass (i.e., No-op at standard I-time).  This statement, or an endin, will cause normal performance to be resumed.

Example:

The following statements will generate an exponential control signal whose value moves from 440 to 880 exactly ten times over the duration p3.

reset:	timout	0, p3 /10, contin	;after p3/10 seconds,

reinit	reset	; reinit both timout

contin:	expon	440, p3/10,880	; and expon

riretum	; then resume perf


Duration Control
DURATION CONTROL STATEMENTS

ihold

turnoff

These statements permit the current note to modify its own duration.

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.

turnoff - 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.

Example:

The following statements will cause a note to terminate when a control signal passes a certain threshold (here the Nyquist frequency).

k1	expon	440, p3/10,880	; begin gliss and continue

if	k1 < sr/2 kgoto contin 	; until Nyquist detected

turnoff	; then quit

contin:	a1	oscil	a1, k1, 1


midi_converters
MIDI CONVERTERS

ival	notnum

ival	veloc

icps	cpsmidi

icps	cpsmidib

kcps	cpsmidib

ioct	octmidi

ioct	octmidib

koct	octmidib

ipch	pchmidi

ipch	pchmidib

kpch	pchmidib

iamp	ampmidi	iscal[, ifn]

kaft	aftouch	iscal

kchpr	chpress	iscal

kbend	pchbend	iscal

ival	midictrl	inum

kval	midictrl	inum

Get a value from the MIDI event that activated this instrument, or from a continuous MIDI controller, and convert it to a locally useful format.

INITIALIZATION

iscal - I-time scaling factor.

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

inum - MIDI controller number.

PERFORMANCE

notnum, veloc - get the MIDI byte value (0 - 127) denoting the note number or velocity  of the current event.

cpsmidi, octmidi, pchmidi - get the note number of the current MIDI event, expressed in cps, oct, or pch units for local processing.

cpsmidib, octmidib, pchmidib - get the note number of the current MIDI event, modify it by the current pitch-bend value, and express the result in cps, oct, or pch units.  Available as an I-time value or as a continuous ksig value.

ampmidi - 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.

aftouch, chpress, pchbend - get the current after-touch, channel pressure, or pitch-bend value for this channel, rescaled to the range 0 - iscal.  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.

midictrl - get the current value (0 - 127) of a specified MIDI controller.


Segment Composed Signals
SIGNAL GENERATORS

Segment Composed Signals

kr	line	ia, idur1, ib

ar	line	ia, idur1, ib

kr	expon 	ia, idur1, ib

ar	expon 	ia, idur1, ib

kr	linseg 	ia, idur1, ib[, idur2, ic[...]]

ar	linseg 	ia, idur1, ib[, idur2, icI...]]

kr	expseg 	ia, idur1, ib[, idur2, ic[...]]

ar	expseg 	ia, idur1, ib[, idur2, ic[...]]

Output values kr or ar trace a straight line (exponential curve) or a series of line segments (exponential segments) between specified points.

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.

Example:

k2	expseg 440, p3/2,880, p3/2,440

This statement creates a control signal which moves exponentially from 440 to 880 and back, over the duration p3.


Phase Generator

kr	phasor 	kcps[, iphs]

ar	phasor 	xcps[, iphs]

Produce a normalized moving phase value.

INITIALIZATION

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

PERFORMANCE

An internal phase is successively accumulated in accordance with the cps 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.

Example:

phasor	1	; cycle once per second

kpch	table	k1 * 12, 1	; through 12-note pch table

a1	oscil	p4, cpspch(kpch), 2	; with continuous sound


Table Access

ir	table	indx, ifn[, ixmode][, ixoff][, iwrap]

ir	tablei	indx, ifn[, ixmode][, ixoff][, iwrap]

kr	table	kndx, ifn[, ixmode][, ixoff][, iwrap]

kr	tablei	kndx, ifn[, ixmode][, ixoff][, iwrap]

ar	table	andx, ifn[, ixmode][, ixoff][, iwrap]

ar	tablei	andx, ifn[, ixmode][, ixoff][, iwrap]

kr	oscil1	idel, kamp, idur, ifn

kr	oscil1i	idel, kamp, idur, ifn

Table values are accessed by direct indexing or by incremental sampling.

INITIALIZATION

ifn - function table number.  tablei, oscil1i require the extended guard point.

ixmode (optional) - ndx data mode.  0 = raw ndx, 1 = normalized (0 to 1).  The default value is 0.

ixoff (optional) - amount by which ndx 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 ndx flag.  0 = nowrap (ndx < 0 treated as ndx=0; ndx > tablesize sticks at ndx=size), 1 = wraparound.  The default value is 0.

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.

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 ndx 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.

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.

tablei and oscil1i are interpolating units in which the fractional part of ndx 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).


Oscillators

kr	oscil	kamp, kcps, ifn[, iphs]

kr	oscili	kamp, kcps, ifn[, iphs]

ar	oscil	xamp, xcps, ifn[, iphs]

ar	oscili	xamp, xcps, ifn[, iphs]

ar	foscil	xamp, kcps, kcar, kmod, kndx, ifn[, iphs]

ar	foscili	xamp, kcps, kcar, kmod, kndx, ifn[, iphs]

Table ifn is incrementally sampled modulo the table length and the value obtained is multiplied by amp.

INITIALIZATION

ifn - function table number.  Requires a wrap-around guard point.

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

The oscil units output 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 cps input value.  While the amplitude and frequency inputs to the K-rate oscils are scalar only, the corresponding inputs to the audio-rate oscils may each be either scalar or vector, thus permitting amplitude and frequency modulation at either sub-audio or audio frequencies.

foscil is a composite unit that effectively banks two oscils 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 * kcar, and modulating frequency = kcps * kmod.  For integral values of kcar and kmod, the perceived fundamental will be the minimum positive value of kcps  * (kcar - n * kmod), n = 1,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.

oscili and foscili differ from oscil and foscil respectively 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.

Example:

k1	oscil	10, 5, 1	; 5 cps vibrato

a1	oscil	5000, 440 + k1, 1	; around A440 + -10 cps


Sampled Sound

ar1 [,ar2]	loscil	 	xamp, kcps, ifn[, ibas][, imod1,ibeg1,iend1][, imod2,ibeg2,iend2]

Read sampled sound (mono or stereo) from a table, with optional sustain and release looping.

INITIALIZATION

ifn - function table number, typically denoting an AIFF sampled sound segment with prescribed looping points.  The source file may be mono or stereo.

ibas (optional) - base frequency in cps of the recorded sound.  This optionally overrides the frequency given in the AIFF file, but is required if the file did not contain one. The default value is 0 (no override).

imod1, mod2 (optional) - 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.

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.

PERFORMANCE

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).

locscil 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.

Example:

inum	notnum

icps	cpsmidi

iamp	ampmidi	3000, 1

ifno	table	inum, 2	;notnum to choose an audio sample

ibas	table	inum, 3

kamp	linenr	iamp, 0, .05, .01	;at noteoff, extend by 50 millisecs

asig	loscil	kamp, icps, ifno, cpsoct(ibas/12. + 3)


Buzzers

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

ar	gbuzz	xamp, xcps, knh, klh, kr, ifn[, iphs]

Output is a set of harmonically related cosine partials.

INITIALIZATION

ifn - table number of a stored function containing (for buzz) a sine wave, or (for gbuzz) a cosine wave.  In either case a large table of at least 8192 points is recommended.

iphs (optional) - 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

These 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.  Must be positive.

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.

kr - 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 * (kr ** n), i.e.  strength values trace an exponential curve.  kr 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 = kr = 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; kr, however, can be varied during performance to good effect.  Both buzz and gbuzz can be amplitude- and/or frequency-modulated by either control or audio signals.

N.B.  These two units have their analogs 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.


Resynthesis

ar	adsyn	kamod, kfmod, ksmod, ifilcod

ar	pvoc	ktimpnt, kfmod, ifilcod [, ispecwp]

Output is an additive set of individually controlled sinusoids, using either an oscillator bank or phase vocoder resynthesis.

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).

ispecwp (optional) - if non-zero, attempts to preserve the spectral envelope while its frequency content is varied by kfmod.    The default value is zero.

PERFORMANCE

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 the Appendix on 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 (currently 50) 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 cps frequency and ksmod modifying the speed with which the millisecond bread-point 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.

pvoc implements signal reconstruction using an fft-based phase vocoder.  The control data stems from a precomputed analysis file with a known frame rate.  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.  kfmod 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.

This implementation of pvoc was written by Dan Ellis.  It is based in part on the system of Mark Dolson, but the pre-analysis concept is new.


Voice Generator

ar	fof	xamp, xfund, xform, koct, kband, kris, kdur, kdec,

iolaps, ifna, ifnb, itotdur[, iphs][, ifmode]

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.

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) - initial phase of the fundamental, expressed as a fraction of a cycle (0 to 1).  The default value is 0.

ifmode (optional) - 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.

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.


Physical Modeling

ar	pluck 	kamp, kcps, icps, ifn, imeth [, iparm1, iparm2]

Audio output is a naturally decaying plucked string or drum sound based on the Karplus-Strong algorithms.

INITIALIZATION

icps - intended pitch value in cps, 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

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.


Random Generators (9)
Random Generators

kr	rand	xamp[, iseed]

kr	randh	kamp, kcps[, iseed]

kr	randi	kamp, kcps[, iseed]

ar	rand	xamp[, iseed]

ar	randh	xamp, xcps[, iseed]

ar	randi	xamp, xcps[, iseed]

Output is a controlled random number series between +amp and -amp

INITIALIZATION

iseed (optional) - seed value for the recursive psuedo-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.  The default seed value is .5.

PERFORMANCE

The internal psuedo-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 cps 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 will produce straightline interpolation between each new number and the next.

Example:

i1	=	octpch(p5)	; center pitch, to be modified

k1	randh	1,10	;10 time/sec by random displacements up to 1 octave	a1	oscil	5000, cpsoct(i1+ k1), 1


Granular Synthesis
Granular Synthesizer.

ar	grain	xamp, xpitch, xdens, kampoff, kpitchoff, kgdur, igfn, iwfn, imgdur

Generates granular synthesis textures.

INITIALIZATION

igfn, igdur - igfn is the ftable number of the grain waveform.  This can be just a sine wave or a sampled sound of any length.  Each grain will start from a random table position and sustain for igdur seconds.

iwfn - Ftable number of the amplitude envelope used for the grains (see also GEN20).

imgdur - Maximum grain duration in seconds.  This the biggest value to be assigned on kgdur.

PERFORMANCE

xamp - Total amplitude of the sound.

xpitch  - Grain frequency in cps.

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 kamp.  This means that the maximum amplitude a grain can have is kamp + kampoff and the minimum is kamp.  If kampoff is set to zero then there is no random amplitude for each grain.

kpitchoff - Maximum pitch deviation from kpitch in cps.  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.


Noise generators

All of the following opcodes operate in i-, k- and a-rate.  The output rate depends on the first letter of the opcode, a for a-rate, k for k- rate and i for i-rate.

xr	xlinrand	krange

xr	xtrirand 	krange

xr	xexprand 	krange

xr	xbexprnd 	krange

xr	xcauchy 	kalpha

xr	xpcauchy  	kalpha

xr	xpoisson 	klambda

xr	xgauss 	krange

xr	xweibull 	ksigma, ktau

xr	xbeta 	krange, kalpha, kbeta

PERFORMANCE

krange - the range of the random number output [0 - krange].

kalpha - controls the spread from zero (big kalpha => big spread).

klambda - the mean of the distribution.

ksigma,ktau - control the distribution. ksigma scales the spread of the distribution. if ktau is greater than one numbers near ksigma are favored, if it is smaller than one small values are favored and if ktau equals 1 the distribution is exponential.

xlinrand outputs postive numbers following a linear distribution while xtrirand outputs both negative and positive numbers.

xexprand outputs positive numbers following an exponential distribution while xbexprnd outputs both negative and positive numbers.

xcauchy produces a Cauchy distribution with both positive and negative numbers while xpcauchy   ouputs positive numbers only.

xpoisson outputs positive numbers following a Poisson distribution.

xgauss is a Gaussian distribution random number generator. Outputs both positive and negative numbers.

xweibull is a Weibull distribution random number generator. Outputs only positive numbers .

xbeta is a beta distribution random number generator.  krange is the range of the random numbers.  If kalpha is smaller than one, smaller values favor values near 0.  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.

Examples:

a1  atrirand  32000	; Audio noise with triangle distribution

k1  kcauchy  10000	; Control noise with Cauchy dist.

i1  ibetarand  30000, .5, .5 ; i-time random value, beta dist.


Envelope Generators
Signal Modifiers

Envelope Generators

kr	linen	kamp, irise, idur, idec

ar	linen	xamp, irise, idur, idec

kr	linenr	kamp, irise, idec, iatdec

ar	linenr	xamp, irise, idec, iatdec

kr	envlpx  	kamp, irise, idur, idec, ifn, iatss, iatdec[, ixmod]

ar	envlpx	xamp, irise, idur, idec, ifn, iatss, iatdec[, ixmod]

linen - apply a straight line rise and decay pattern to an input amp signal.

linenr - apply a straight line rise, then an exponential decay while the note is extended in time.

envlpx - apply an envelope consisting of 3 segments: 1) stored function rise shape, 2) modified

exponential "pseudo steady state", 3) exponential decay

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 > l causes an exponential growth, and < l an exponential decay.  A 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 neg 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

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 (linen) or modified by the first exponential pattern (envlpx).  If linen rise and decay periods overlap then both modifications will be in effect for that time; in envlpx that will cause a truncated decay.  If the overall duration idur is exceeded in performance, the final decay will continue on in the same direction, going negative for linen but tending asymptotically to zero in envlpx.

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.


First Order Filters

kr	port	ksig, ihtim[, isig]

ar	tone	asig, khp[, istor]

ar	atone	asig, khp[, istor]

ar	reson	asig, kcf, kbw[, iscl, istor]

ar	areson	asig, kcf, kbw[, iscl, istor]

A control or audio signal is modified by a low- or band-pass recursive filter with variable frequency response.

INITIALIZATION

isig - initial (i.e. previous) value for internal feedback.  The default value is 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.

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 (e.g. see balance).  The default value is 0.

PERFORMANCE

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.

tone implements a first-order recursive low-pass filter in which the variable khp (in cps) determines the response curve's half -power point.  Half power is defined as peak power / root 2.

reson is a second-order filter in which kcf controls the center frequency, or cps position of the peak response, and kbw controls its bandwidth (the cps difference between the upper and lower half -power points).

atone, areson are filters whose transfer functions are the complements of tone and reson.  atone is thus a form of high-pass filter and areson a notch filter whose transfer functions represent the "filtered out" aspects of their complements.  Note, however, that power scaling is not normalized in atone, 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 (iscl 1 only, iscl 2 giving twice amplitude).  This property is useful for controlled mixing of different sources (e.g., 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.


Dynamic Spectrum Modifier

krmsr,krmso,kerr,kcps	lpread 	ktimpnt, ifilcod[, inpoles][, ifrmrate]

ar	lpreson 	asig

ar	lpfreson 	asig, kfrqratio

These units, used as a read/reson pair, use a control file of time-varying filter coefficients to dynamically modify the spectrum of an audio signal.

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, ifrmrate (optional) - number of poles, and frame rate per second in the lpc analysis.  These arguments are required only when the control file does not have a header; they are ignored when a header is detected.  The default value for both is zero.

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 cps.

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.


Gain Units

kr	rms	asig[, ihp, istor]

nr	gain	asig, krms[, ihp, istor]

ar	balance	asig, acomp[, ihp, istor]

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

INlTlALIZATlON

ihp (optional) - half-power point (in cps) of a special 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

rms output values kr will trace the rms value of the audio input asig.  This unit is not a signal modifier,  but functions rather as a signal power-guage.

gain provides an amplitude modification of asig so that the output ar has rms power equal to krms.  rms and gain used together (and given matching ihp values) will provide the same effect as balance.

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.

Example:

asrc	buzz	10000,440, sr/440, 1	; band-limited pulse train

a1	reson	asrc, 1000,100	; sent through

a2      	reson    	a1,3000,500 	; 2 filters

afin	balance	a2, asrc 	; then balanced with source


Sample Level Operators

kr	downsamp	asig[, iwlen]

ar	upsamp 	ksig

ar	interp	ksig[, istor]

kr	integ	ksig[, istor]

ar	integ	asig[, istor]

kr	diff	ksig[, istor]

ar	diff	asig[, istor]

kr	samphold	xsig, kgate[, ival, ivstor]

ar	samphold	asig, xgate[, ival, ivstor]

Modify a signal by up- or down-sampling, integration, and differentiation.

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.

istor (optional) - initial disposition of internal save space (see reson).  The default value is 0.

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

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.

upsamp, interp convert a control signal to an audio signal.  The first does it by simple repetition of the kval, the second by linear interpolation between successive kvals.  upsamp is a slightly more efficient form of the assignment, "asig = ksig".

integ, 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 * sin(pi * cps / 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.

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.

Example:

asrc	buzz	10000,440,20, 1	; band-limited pulse train

adif	diff	asrc	; emphasize the highs

anew	balance	adif, asrc	;       but retain the power

agate	reson	asrc,0,440	; use a lowpass of the original

asamp	samphold	anew, agate	;       to gate the new audiosig

aout	tone	asamp,100	; smooth out the rough edges


Delay Lines
Delay Path

ar	delayr	idlt[, istor]

delayw	asig

ar	delay	asig, idlt[, istor]

ar	delay1	asig[, istor]

A signal can be read from or written into a delay path, or it can be automatically delayed by some time interval.

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.

istor (optional) - 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 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).

delay is a composite of the above two units, 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 is a special form of delay that serves to delay the audio signal asig by just one sample.  It is thus functionally equivalent to "delay  asig, 1/sr" but is more efficient in both time and space.  This unit is particularly useful in the fabrication of generalized non-recursive filters.

Example:

tigoto	contin	; except on a tie,

a2	delay	a1, .05, 0	; begin 50 msec clean delay of sig

contin:


Delay Tap
Delay Taps

ar	deltap	kdlt

ar	deltapi	xdlt

Tap a delay line at variable offset times.

PERFORMANCE

These units 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.

deltap extracts sound by reading the stored samples directly; 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.

The arguments kdlt, xdlt specify 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.

These units 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.

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 fastpaced changes, however, one should provide a higher resolution audio-rate timeshift as input.

Example:

asource	buzz	1, 440, 20, 1

atime	linseg	1, p3/2,.01, p3/2,1	; trace a distance in secs

ampfac	=	1/atime/atime	;     and calc an amp factor

adump	delayr	1	; set maximum distance

amove	deltapi	atime	; move sound source past

delays	asource	;     the listener

out	amove * ampfac


Reverberation Units

ar	comb	asig, krvt, ilpt[, istor]

ar	alpass	asig, krvt, ilpt[, istor]

ar	reverb	asig, krvt[, istor]

An input signal is reverberated for krvt seconds with "colored" (comb), flat (alpass), or "natural room" (reverb) frequency response.

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 4n * sr bytes.  comb and alpass delay space is allocated and returned as in delay.

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

PERFORMANCE

These filters reiterate 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; alpass output will begin to appear immediately.

A standard reverb unit is composed of four comb filters in parallel followed by two alpass units in series.  Looptimes 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.  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.

Example:

ga1	init	0	; init an audio receiver/mixer

instr	1	; instr (there may be many copies)

a1	oscili	8000, cpspch(p5), 1	; generate a source signal

out	a1	; output the direct sound

ga1	=	ga1 + a1	; and add to audio receiver

endin

instr	99	; (highest instr number executed last)

a3	reverb	ga1, 1.5	; reverberate whatever is in ga1

out	a3	; and output the result

ga1	=	0	; empty the receiver for the next pass

endin


Butterworth filters

ar	butterhp	asig, kfreq

ar	butterlp	asig, kfreq

ar	butterbp	asig, kfreq, kband

ar	butterbr	asig, kfreq, kband

Implementations of second-order hipass, lopass, bandpass and bandreject Butterworth filters.

PERFORMANCE

These new 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  - Cuttoff or center frequency for each of the filters.

kband  - Bandwidth of the bandpass and bandreject filters.

EXAMPLE

asig	rand	10000	      	; White noise signal

alpf	butterlp	asig, 1000    	; cutting frequencies above1K

ahpf	butterhp	asig, 500     	; passing frequencies above 500Hz

abpf	butterbp	asig, 2000, 100 ; passing only 1950 to 2050 Hz

abrf	butterbr	asig, 4500, 200 ; cutting only 4400 to 4600 Hz


Variable Time Delay

ar	vdelay	asig, adel, imaxdel

This is an interpolating variable time delay, it is not very different from the existing implementation (deltapi), it is only easier to use.

INITIALIZATION

imaxdel - Maximum value of delay in samples.  If adel gains a value greater than imaxdel it is folded around imaxdel.  This should not happen.

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 samples.  Note that linear functions have no pitch change effects.  Fast changing values of adel will cause discontinuities in the waveform resulting noise.

Example

f1 0 8192 10 1

ims = 100	; Maximum delay time in msec

a1	oscil	10000, 1737, 1	; Make a signal

a2	oscil	ims/2, 1/p3, 1	; Make an LFO

a2	=	a2 + ims/2	; Offset the LFO so that it is positive

a3	vdelay	a1, a2, ims	; Use the LFO to control delay time

out	a3

Two important points here.  First, the delay time must be always positive.  And second, even though the delay time can be controlled in k-rate, it is not advised to do so, since sudden time changes will create clicks.


Multitap delay

ar	multitap	asig, itime1, igain1, itime2, igain2 . . .

Multitap delay line implementation.

INITIALIZATION

itime, igain - set the position and gain of each tap.

PERFORMANCE

asign - Input signal.

Example:

a1	oscil	1000, 100, 1

a2	multitap	a1, 1.2, .5, 1.4, .2

out	a2

This results in two delays, one with length of 1.2 and gain of .5, and one with length of 1.4 and gain of .2.


Reverberation Unit (2)

ar	reverb2	asig, ktime, khdif

This is a reverberator consisting of 6 parallel comb-lowpass filters being fed into a series of 5 allpass filters.

PERFORMANCE

ktime - time (sec) of the reverberation.

khdif - 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 that lower ones.

asig - input signal

EXAMPLE:

a1	oscil	10000, 100, 1

a2	reverb2	a1, 2.5, .3

out	a1 + a2 * .2

This results in a 2.5 sec reverb with faster high frequency attenuation.


Envelope follower

kr	follow	asig,  idt

Envelope follower unit generator.

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.

EXAMPLE

k1	line	0, p3, 30000	; Make k1 a simple envelope

a1	oscil	k1, 1000, 1	; Make a simple signal using k1

ak1	follow	a1, .02	; ak1 is now like k1

a2	oscil	ak1, 1000, 1	; Make a simple signal using ak1

out	a2	; Both a1 and a2 are the same

To avoid zipper noise, by discontinuities produced from complex envelope tracking, a lowpass filter could be used, to smooth the estimated envelope.


Power Function
Power functions

ir	ipow	iarg, kpow

kr	kpow	karg, kpow, [inorm]

ar	apow	aarg, kpow, [inorm]

Computes xarg  to the power of kpow  and scales the result by inorm.

INITIALIZATION

inorm - 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 !

iarg  - If you are using ipow this is the base.

PERFORMANCE

karg  - If you are using kpow this is the base.

aarg  - If you are using apow this is the base.

EXAMPLES:

1.	i2t2	ipow	2,2	; Computes 2^2.

2.	kline	line	0, 1, 4

kexp	kpow	kline, 2, 4

This feeds a linear function to kpow and scales that to the line's

peak value.  The output will be an exponential curve with the same

range as the input line.

3.	iamp ipow	10, 2

a1	oscil	iamp, 100, 1

a2	apow	a1, 2, iamp

out a2

This will output a sine with its negative part folded over the amp

axis.  The peak value will be iamp = 10^2 = 100.


Convolution Operator

ar1[,ar2[,ar3[,ar4]]]  convolve  ain,ifilcod,channel

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.

INITIALISATION

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 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.

channel - integer denoting the channel of the impulse response to be used for the convolution. 0 (the default) means to use all channels. For multi-channel output, the number of channels in the impulse           response must match the number of output signals.

PERFORMANCE

ain - input 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 is small enough.


Octave Decimation
OPERATIONS USING SPECTRAL DATA-TYPES

These units generate and process non-standard signal data types, such as down-sampled time-domain control signals and audio signals, and their frequency-domain (spectral) representations.  The new data types (d-, w-) are self-defining, and the contents are not processable by any other Csound units.  These unit generators are experimental, and subject to change between releases; they will also be joined by others later.

dsig	octdown	xsig, iocts, isamps[, idisprd]

wsig	noctdft	dsig, iprd, ifrqs, iq[, ihann, idbout, idsines]

INITIALIZATION

idisprd (optional) - if non-zero, display the output every idisprd seconds.  The default value is 0 (no display).

ihann, idbout, idsines (optional) - if non-zero, then respectively: apply a hanning window to the input; convert the output magnitudes to dB; display the windowed sinusoids used in DFT filtering.  The default values are 0,0,0 (rectangular window, magnitude output, no sinusoid display).

PERFORMANCE

octdown - put signal asig or ksig through iocts successive applications of octave decimation and downsampling, and preserve isamps down-sampled values in each octave.  Optionally display the composite buffer every idisprd seconds.

noctdft - generate a constant-Q, exponentially-spaced DFT across all octaves of the multiply-downsampled input dsig.  Every iprd seconds, each octave of dsig is optionally windowed (ihann non-zero), filtered (using ifrqs parallel filters per octave, exponentially spaced, and with frequency/bandwidth Q of iq), and the output magnitudes optionally converted to dB (idbout non-zero).  This unit produces a self-defining spectral datablock wsig, whose characteristics are readable by any units that receive it as input, and for which it becomes the template for output.  The information used in producing this wsig (iprd, iocts, ifrqs) is passed via the data block to all derivative wsigs, and is thus available to subsequent spectral operators if needed.

Example:

asig	in	; get external audio

dsamp	octdown 	asig, 6, 180, 0	; downsample in 6 octaves

wsig	noctdft   	dsamp, .02, 12, 33, 0, 1, 1	; and calc 72-point dft (dB)


Spectrum Local Operators

wsig	specaddm	wsig1, wsig2[, imul2]

wsig	specdiff	wsigin

wsig	specscal	wsigin, ifscale, ifthresh

wsig	spechist	wsigin

wsig	specfilt	wsigin, ifhtim

INITIALIZATION

imul2 (optional) - if non-zero, scale the wsig2 magnitudes before adding.  The default value is 0.

PERFORMANCE

specaddm - 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 - find 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.

specscal - scale 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.

spechist - accumulate 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.

specfilt - filter 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.

Example:

wsig2	specdiff   	wsig1	; sense onsets

wsig3	specfilt  	wsig2, 2	; absorb slowly

specdisp 	wsig2, .1	; & display both spectra

specdisp 	wsig3, .1


Spectrum Global Operators

koct	specptrk 	wsig, inptls, irolloff, iodd[, interp, ifprd, iwtflg]

ksum	specsum 	wsig[, interp]

specdisp	wsig, iprd[, iwtflg]

INITIALIZATION

interp (optional) - if non-zero, interpolate the output signal (koct or ksum).  The default value is 0 (repeat the signal value between changes).

ifprd (optional) - if non-zero, display the internally computed fundamental spectrum.  The default value is 0 (no display).

iwtflg (optional) - wait flag.  If non-zero, hold each display until released by the user.  The default value is 0 (no wait).

PERFORMANCE

specptrk - estimate the pitch of the most prominent complex tone in the spectrum.  At note initialization this unit creates a set of inptls harmonically related partials (odd if iodd non-zero) with amplitude rolloff to the fraction irolloff per octave. Then at each new frame of wsig, the spectrum is cross-correlated with this set, and the result at each point added to an internal copy of the spectrum (optionally displayed).  A pitch is then estimated, and the result is released in decimal octave form.  Between frames, the output is either repeated or interpolated at the K-rate.

specsum - sum 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.

specdisp - display the magnitude values of spectrum wsig every iprd seconds (rounded to some integral number of wsig's originating iprd).

Example:

ksum	specsum 	wsig,  1	; sum the spec bins, and ksmooth

if	ksum < 2000   kgoto  zero	; if sufficient amplitude

koct	specptrk   	wsig, 8, .8, 0 	;    pitch-track the signal

kgoto	contin

zero:	koct	=	0	; else output zero

contin:


Tempo Evaluation
SENSING & CONTROL

Tempo Evaluation

ktemp	tempest	kin, iprd, imindur, imemdur, ihp, ithresh, ihtim, ixfdbak,

istartempo, ifn[, idisprd, itweek]

Estimate the tempo of beat patterns in a control signal.

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 cps) 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 cps.

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.

Example:

ksum	specsum	wsignal, 1	; sum the amps of a spectrum

ktemp	tempest	ksum, .02, .1, 3, 2, 800, .005, 0, 60, 4, .1, .995	; and look for beats


Sensing and Control (Misc)
Miscellaneous

kx, ky	xyin	iprd, ixmin, ixmax, iymin, iymax[, ixinit, iyinit]

tempo	ktempo, istartempo

Sense the cursor position in an input window.  Apply tempo control to an uninterpreted score.

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.

istartempo - initial tempo (in beats per minute).  Typically 60.

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 Realtime control,  but continuous motion should be avoided if iprd is unusually small.

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.

Example:

          kx,ky	xyin	.05, 30, 0, 120, 0, 75	; sample the cursor

tempo	kx, 75                    	; and control the tempo of performance


Audio Input/Output
SIGNAL INPUT & OUTPUT

 Audio Input/Output

a1	in

a1, a2	ins

a1, a2, a3, a4	inq

a1	soundin	ifilcod[, iskptim][, iformat]

a1, a2	soundin	ifilcod[, iskptim][, iformat]

a1, a2, a3, a4	soundin	ifilcod[, iskptim][, iformat]

out	asig

outs1	asig

outs2	asig

outs	asig1, asig2

outq1	asig

outq2 	asig

outq3	asig

outq4	asig

outq	asig1, asig2, asig3, asig4

These units read/write audio data from/to an external device or stream.

INITIALIZATION

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 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).  If iformat = 0 it is taken from the soundfile header, and if no header from the csound -o command flag.  The default value is 0.

PERFORMANCE

in, ins, inq - copy the current values from the standard audio input buffer.  If the command-line flag -i 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 units can read freely from this buffer.

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 unit 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 units within a single instrument or orchestra; also, two or more of them can read simultaneously from the same external file.

out, outs, outq send 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, or quad) must agree with nchnls, but units can be chosen to direct sound to any particular channel: outs1 sends to stereo channel 1, outq3 to quad channel 3, etc.


Pan Localisation

a1, a2, a3, a4	pan	asig, kx, ky, ifn[, imode][, ioffset]

Distribute an audio signal amongst four channels with localization control.

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 (enscribed) 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.

Example:

      	instr	1

k1	phasor  1/p3	; fraction of circle

k2	tablei	k1, 1, 1	; sin of angle (sinusoid in f1)

k3	tablei	k1, 1, 1, .25, 1	; cos of angle (sin offset 1/4 circle)

a1	oscili	10000,440, 1 	; audio signal..

a1,a2,a3,a4	pan	a1, k2/2, k3/2, 2, 1, 1	; sent in a circle (f2=1st quad sin)

outq	a1, a2, a3, a4

endin


Control Signal Dump

kdump	ksig, ifilname, iformat, iprd

kdump2	ksig1, ksig2, ifilname, iformat, iprd

kdump3	ksig1, ksig2, ksig3, ifilname, iformat, iprd

kdump4	ksig1, ksig2, ksig3, ksig4, ifilname, iformat, iprd

Periodically write orchestra control-signal values to a named external file in a specific format.

INITlALIZATION

ifilname - character string (in double quotes, spaces permitted) denoting the external file name.  May be either 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 character (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

These units allow up to four generated control signal values to be saved in a named external file.  The file contains no self-defining header information, but is a regularly sampled time series, suitable for later input or analysis.  There may be any number of kdump units in an instrument or orchestra.

Example:

knum	=	knum + 1	; at each k-period

ktemp	tempest	krms, .02, .1, 3, 2, 800, .005, 0, 60, 4, .1 .995	; estimate the tempo

koct	specptrk	wsig, 6, .9, 0	; and the pitch

kdump3	knum, ktemp, cpsoct(koct), "what happened when", 8, 0	; & save them


SIGNAL DISPLAY

print	iarg[, iarg,...]

display	xsig, iprd[, inprds][, iwtflg]

dispfft	xsig, iprd, iwsiz[, iwtyp][, idbouti][, iwtflg]

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.

INITlALIZATION

iprd - the period of display in seconds.

inprds (optional) - 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).

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) - window type.  0 = rectangular, 1 = hanning.  The default value is 0 (rectangular).

idbout (optional) - units of output for the Fourier coefficients.  0 = magnitude, 1 = decibels.  The default is 0 (magnitude).

iwtflg (optional) - wait flag.  If non-zero, each display is held until released by the user.  The default value is 0 (no wait).

PERFORMANCE

print - print the current value of the I-time arguments (or expressions) iarg at every I-pass through the instrument.

display - display the audio or control signal xsig every iprd seconds, as an amplitude vs. time graph.

dispfft - display the Fourier Transform of an audio or control signal (asig or ksig) every iprd seconds using the Fast Fourier Transform method.

Example:

k1	envlpx	l, .03, p3, .05, l, .5, .0l	; generate a note envelope

display	k1, p3	; and display entire shape


Score Description
THE STANDARD NUMERIC SCORE

A score is a data file that provides information to an orchestra about its performance.  Like an orchestra file, a score file is made up of statements in a known format.  The Csound orchestra expects to be handed a score comprised mainly of ascii numeric characters.  Although most users will prefer a higher level score language such as provided by Cscore, Scot, or another score-generating program, each resulting score must eventually appear in the format expected by the orchestra.  A Standard Numeric Score can be created and edited directly by the beginner using standard text editors; indeed, some users continue to prefer it.  The purpose of this section is to describe this format in detail.

The basic format of a standard numeric score statement is:

      opcode p1 p2 p3 p4...             ;comments

The opcode is a single character, always alphabetic.  Legal opcodes are f, i, a, t, s, and e, the meanings of which are described in the following pages.  The opcode is normally the first character of a line; leading spaces or tabs will be ignored.  Spaces or tabs between the opcode and p1 are optional.

p1, p2, p3, etc...  are parameter fields (pfields).  Each contains a floating point number comprised of an optional sign, digits, and an optional decimal point.  Expressions are not permitted in Standard Score files.  pfields are separated from each other by one or more spaces or tabs, all but one space of which will be ignored.

Continuation lines are permitted.  If the first printing character of a new scoreline is not an opcode, that line will be regarded as a continuation of the pfields from the previous scoreline.

Comments are optional and are for the purpose of permitting the user to document his score file.  Comments always begin with a semicolon (;) and extend to the end of the line.  Comments will not affect the pfield continuation feature.

Blank lines or comment-only lines are legal (and will be ignored).


Preprocessing of Score
Preprocessing of Standard Scores

A Score (a collection of score statements) is divided into time-ordered sections by the s statement.  Before being read by the orchestra, a score is preprocessed one section at a time.  Each section is normally processed by 3 routines: Carry, Tempo, and Sort.

1.  Carry - within a group of consecutive i statements whose p1 whole numbers correspond, any pfield left empty will take its value from the same pfield of the preceding statement.  An empty pfield can be denoted by a single point (.) delimited by spaces.  No point is required after the last nonempty pfield.  The output of Carry preprocessing will show the carried values explicitly.  The Carry Feature is not affected by intervening comments or blank lines; it is turned off only by a non-i statement or by an i statement with unlike p1 whole number.

An additional feature is available for p2 alone.  The symbol + in p2 will be given the value of p2 + p3 from the preceding i statement.  This enables note action times to be automatically determined from the sum of preceding durations.  The + symbol can itself be carried.  It is legal only in p2.

E.g.:	the statements

i1	0	.5   	100

i .	+

i

will result in

i1 	0    	.5   	100

i1	.5	.5	100

 	i1  	1     	.5   	100

The Carry feature should be used liberally.  Its use, especially in large scores, can greatly reduce input typing and will simplify later changes.

2.  Tempo - this operation time warps a score section according to the information in a t statement.  The tempo operation converts p2 (and, for i statements, p3) from original beats into real seconds, since those are the units required by the orchestra.  After time warping, score files will be seen to have orchestra-readable format demonstrated by the following:

i p1 p2beats p2seconds p3beats p3seconds p4 p5 ....

3.  Sort - this routine sorts all action-time statements into chronological order by p2 value.  It also sorts coincident events into precedence order.  Whenever an f statement and an i statement have the same p2 value, the f statement will precede.  Whenever two or more i statements have the same p2 value, they will be sorted into ascending p1 value order.  If they also have the same p1 value, they will be sorted into ascending p3 value order.  Score sorting is done section by section (see s statement).  Automatic sorting implies that score statements may appear in any order within a section.

N.B.  The operations Carry, Tempo and Sort are combined in a 3-phase single pass over a score file, to produce a new file in orchestra-readable format (see the Tempo example).  Processing can be invoked either explicitly by the scsort command, or implicitly by csound which processes the score before calling the orchestra.  Source-format files and orchestra-readable files are both in ascii character form, and may be either perused or further modified by standard text editors.  Userwritten routines can be used to modify score files before or after the above processes, provided the final orchestra-readable statement format is not violated.  Sections of different formats can be sequentially batched; and sections of like format can be merged for automatic sorting.


Next-P and Previous-P
Next-P and Previous-P Symbols

At the close of any of the above operations, three additional score features are interpreted during file writeout: next-p, previous-p, and ramping.

i statement pfields containing the symbols npx or ppx (where x is some integer) will be replaced by the appropriate pfield value found on the next i statement (or previous i statement) that has the same p1.  For example, the symbol np7 will be replaced by the value found in p7 of the next note that is to be played by this instrument.  np and pp symbols are recursive and can reference other np and pp symbols which can reference others, etc.  References must eventually terminate in a real number or a ramp symbol (see below).  Closed loop references should be avoided.  np and pp symbols are illegal in p1,p2 and p3 (although they may reference these).  np and pp symbols may be Carried.  np and pp references cannot cross a Section boundary.  Any forward or backward reference to a non-existent note-statement will be given the value zero.

E.g.:	the statements

i1	0 	1 	10 	np4 	pp5

i1	1	1	20

i1	1	1	30

will result in

 	i1	0 	1 	10	20 	0

i1	1 	1 	20 	30 	20

i1	2 	1 	30 	0 	30

np and pp symbols can provide an instrument with contextual knowledge of the score, enabling it to glissando or crescendo, for instance, toward the pitch or dynamic of some future event (which may or may not be immediately adjacent).  Note that while the Carry feature will propagate np and pp through unsorted statements, the operation that interprets these symbols is acting on a time-warped and fully sorted version of the score.


Ramping

i statement pfields containing the symbol < will be replaced by values derived from linear interpolation of a time-based ramp.  Ramps are anchored at each end by the first real number found in the same pfield of a preceding and following note played by the same instrument.

E.g.:	the statements

i1	0	1 	100

i1	1	1	<

i1	2	1	<

i1	3	1	400

i1	4	1	<

i1	5	1	0

will result in

 	i1	0	1	100

i1	1	1	200

i1	2	1	300

i1	3	1	400

i1	4	1	200

i1	5	1	0

Ramps cannot cross a Section boundary.  Ramps cannot be anchored by an np or pp symbol (although they may be referenced by these).  Ramp symbols are illegal in p1, p2 and p3.  Ramp symbols may be Carried.  Note, however, that while the Carry feature will propagate ramp symbols through unsorted statements, the operation that interprets these symbols is acting on a time-warped and fully sorted version of the score.  In fact, time-based linear interpolation is based on warped score-time, so that a ramp which spans a group of accelerating notes will remain linear with respect to strict chronological time.


F Statements
F STATEMENT (or  FUNCTION TABLE STATEMENT)

f  p1  p2  p3  p4 ...

This causes a GEN subroutine to place values in a stored function table for use by instruments.

PFIELDS

p1	Table number (from 1 to 200) 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 (see below).

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	|

p6	|   Parameters whose meaning is determined by the particular GEN routine.

.	|

.	|

SPECIAL CONSIDERATIONS

Function tables are arrays of floating-point values.  Arrays can be of any length in powers 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 envlpx, oscil1, oscil1i, etc.

Table space is allocated in primary memory, along with instrument data space.  The maximum table number has a soft limit of 200;  this can be extended if 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.

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).


I Statements
I STATEMENT (INSTRUMENT or NOTE STATEMENT)

i  p1  p2  p3  p4  ...

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.

PFIELDS

p1	Instrument number (from 1 to 200), 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 zero value will invoke an initialization pass

without performance (see also instr).

p4	|

p5	|   Parameters whose significance is determined by the instrument.

.	|

.	|

SPECIAL CONSIDERATIONS

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 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.


A Statements
A STATEMENT (or ADVANCE STATEMENT)

a  p1  p2  p3

This causes score time to be advanced by a specified amount without producing sound samples.

PFIELDS

p1	carries no meaning.  Usually zero

p2	Action time, in beats, at which advance is to begin.

p3	Durational span (distance in beats) of time advance.

p4	|

p5	| 	These carry no meaning.

.

.

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 distance 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.


T Statement
T STATEMENT (TEMPO STATEMENT)

t  p1  p2  p3  p4  .....  (unlimited)

This statement sets the tempo and specifies the accelerations and decelerations for the current section.  This is done by converting beats into seconds.

PFIELDS

p1	must be zero

p2	initial tempo in beats per minute

p3, p5, p7, ...	times in beats (in non-decreasing order)

p4, p6, p8, ...	tempi for the referenced beat times

SPECIAL CONSIDERATIONS

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.


S STATEMENT

s  anything

The s statement marks the end of a section.

PFIELDS

All pfields are ignored.

SPECIAL CONSIDERATIONS

Sorting of the i, f and a statements 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 f 0 statement.

A section ending automatically invokes a Purge of inactive instrument and data spaces.

N.B.	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.


E STATEMENT

e anything

This statement may be used to mark the end of the last section of the score.

PFIELDS

All pfields are ignored.

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.


GEN01
Table Generation Routines

The GEN subroutines are function-drawing procedures called by f statements to construct stored wavetables.  They are available throughout orchestra performance, and can be invoked at any point in the score as given by p2.  p1 assigns a table number, and p3 the table size (see f statement).  p4 specifies the GEN routine to be called; each GEN routine will assign special meaning to the pfield values that follow.

GEN01

This subroutine transfers data from a soundfile into a function table.

f  #  time  size  1  filcod  skiptime  format  channel

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.  If the source soundfile is of type AIFF, 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.  An AIFF source 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:

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 flag.

channel - read only a specific channel (1,2,3 or 4) from the file.  A zero means read all channels.

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.

Examples:

f   1  0  8192  1  23  0  4  0

f   2  0  0  -1  "trumpet  A#5"  0  4  0

The tables are filled from 2 files, Òsoundin.23Ó and Òtrumpet A#5Ó, expected in SSDIR or SFDIR.  The first table is pre-allocated;  the second is allocated dynamically, and its rescaling is inhibited.


GEN02

This subroutine transfers data from immediate pfields into a function table.

f  #  time  size  2  v1  v2  v3  .  .  .

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, ... - 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 150).  The values copied may include the table guard point;  any table locations not filled will contain zeros.

Note:

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.

Example:

f   1  0  16  -2  0  1  2  3  4  5  6  7  8  9  10  11  0

This calls upon GEN02 to place 12 values plus an explicit wrap-around guard value into a table of size next-highest power of 2.  Rescaling is inhibited.


GEN03

This subroutine generates a stored function table by evaluating a polynomial in x over a fixed inter- val and with specified coefficients.

f  #  time  size  3  xval1  xval2  c0  c1  c2  .  .  .  cn

size - number of points in the table.  Must be a power of 2 or a power-of-2 plus 1 (see f statement).

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

                        c0 + c1x + c2x2 + .  .  .  + cnxn

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.

Example:

f   1  0   1025  3  -1  1  5  4  3  2  2  1

This calls GEN03 to fill a table with a 4th order polynomial function over the x-interval -1 to 1.  The origin will be at the offset position 512.  The function is post-normalized.


GEN04

This subroutine generates a normalizing function by examining the contents of an existing table.

f  #  time  size  4  source#  sourcemode

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.

Example:

f   2   0   512   4    1   1

This creates a normalizing function for use in connection with the GEN03 table 1 example.  Midpoint bipolar offset is specified.


GEN05, GEN07

These subroutines are used to construct functions from segments of exponential curves (GEN05) or straight lines (GEN07).

f  #    time    size   5   a   n1   b   n2   c  .  .  .

f  #    time    size   7   a   n1   b   n2   c  .  .  .

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, .  .  .  For GEN05 these must be nonzero and must be alike in sign.  No such restrictions exist for GEN07.

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.

Example:

f   1   0   256   7   0   128   1   0   -1   128   0

This describes a single-cycle sawtooth whose discontinuity is mid-way in the stored function.


GEN06

This subroutine will generate a function comprised of segments of cubic polynomials, spanning specified points just three at a time.

f  #   time   size   6   a   n1   b   n2   c   n3   d .  .  .

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.

Example:

f    1    0    65    6   0   16   .5    16   1   16   0   16   -1

This creates a curve running 0 to 1 to -1, with a minimum, maximum and minimum at these values respectively.  Inflexions are at  .5 and 0, and are relatively smooth.


GEN08

This subroutine will generate a piecewise cubic spline curve, the smoothest possible through all specified points.

f   #    time    size    8    a    n1    b    n2    c    n3    d  .  .  .

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 ... - 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.

Examples:

f    1    0    65    8    0    16    0    16    1    16    0    16    0

This example creates a curve with a smooth hump in the middle, going briefly negative outside the hump then flat at its ends.

f    2    0    65    8    0    16    0   .1    0    15.9    1    15.9    0    .1    0    16    0

This example is similar, but does not go negative.


GEN09, GEN10, GEN19

These subroutines generate composite waveforms made up of weighted sums of simple sinusoids.  The specification of each contributing partial requires 3 pfields using GEN09, 1 using GEN10, and 4 using GEN19.

f   #    time    size    9      pna     stra    phsa    pnb    strb    phsb  .  .  .

f   #    time    size  10      str1     str2    str3     str4  .  .  .  .

f   #    time    size  19      pna     stra    phsa    dcoa   pnb    strb    phsb   dcob  .  .  .

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).

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.

Examples:

f    1    0    1024      9    1    3      0    3    1    0    9   .3333    180

f    2    0    1024    19    .5   1  270    1

f 1 combines partials l, 3 and 9 in the relative strengths in which they are found in a square wave, except that partial 9 is upside down.   f 2 creates a rising sigmoid [0 - 2].   Both will be rescaled.


GEN11

This subroutine generates an additive set of cosine partials, in the manner of Csound generators buzz and gbuzz.

f    #    time    size    11    nh    lh    r

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 buzz and 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 dynamic buzz units.  However, the spectral content is invariant, and care is necessary lest the higher partials exceed the Nyquist during sampling to produce foldover.

Examples:

f  1    0    2049   11    4

f  2    0    2049   11    4    1    1

f  3    0    2049  -11    7    3   .5

The first two tables will contain identical band-limited pulse waves of four equal-strength harmonic partials beginning with the fundamental.  The third table will sum seven consecutive harmonics, beginning with the third, and at progressively weaker strengths (1, .5, .25, .125 .  .  .).  It will not be post-normalized.


GEN12

This generates the log of a modified Bessel function of the second kind, order 0, suitable for use in amplitude-modulated FM.

f    #    time    size    -12    xint

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 +int] 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.

Example:

f    1    0    2049    -12    20

This draws an unscaled ln(I0(x)) from 0 to 20.


GEN13, GEN14

These subroutines use Chebyshev coefficients to generate stored polynomial functions which, under waveshaping, can be used to split a sinusoid into harmonic partials having a predefinable spectrum.

f    #    time    size    13    xint    xamp    h0    h1    h2  .  .  .  hn

f    #    time    size    14    xint    xamp    h0    h1    h2  .  .  .  hn

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, ....  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.

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.

Example:

f    1    0   1025    13    1   1    0    5    0    3    0    1

This creates a function which, under waveshaping, will split a sinusoid into 3 odd-harmonic partials of relative strength 5:3:1.


GEN15

This subroutine creates two tables of stored polynomial functions, suitable for use in phase quadrature operations.

f    #    time    size    15    xint    xamp    h0    phs0    h1    phs1    h2    phs2  .  .  .

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.

Note:

GEN15 creates two tables of equal size, labelled f # and f # + 1.  Table # will contain a Chebyshev function of the first kind, drawn using GEN03 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.


GEN17

This subroutine creates a step function from given x-y pairs.

f    #    time    size    17    x1  a  x2  b  x3  c  .  .  .

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.

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).

Example:

f  1  0  128  -17   0  1   12  2   24  3   36  4   48  5   60  6   72  7   84  8

This describes a step function with 8 successively increasing levels, each 12 locations wide except the last which extends its value to the end of the table.  Rescaling is inhibited.  Indexing into this table with a MIDI note-number would retrieve a different value every octave up to the eighth, above which the value returned would remain the same.


GEN20

This subroutine generates functions of different windows.  These windows are usually used for spectrum analysis or for grain envelopes.

f #	time	size	20	window	max	opt

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 - Sinc

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 Kaiser window.

Examples:

f	1	0	1024	20	5

This creates a function which contains a 4 - term Blackman - Harris  window with maximum value of 1.

f	1	0	1024	-20	2	456

This creates a function that contains a Hanning window with a maximum value of 456.

f	1	0	1024	-20	1

This creates a function that contains a Hamming window with a maximum value of 1.

f	1	0	1024	20	7	1	2

This creates a function that contains a Kaiser window with a maximum value of 1.  The extra argument specifies how `open' the window is, for example a value of 0 results in a rectangular window and a value of 10 in a Hamming like window.


GEN21

This generates tables of different random distributions. (see also noise generators).

f #	time	size	21	type	lvl arg1 arg2

Time and size are the usual Gen function arguments.  Type defines the distribution to be used.

1   - Uniform

2   - Linear

3   - Triangular

4   - Exponential

5   - Biexponential

6   - Gaussian

7   - Cauchy

8   - Positive Cauchy

9   - Beta

10  - Weibull

11  - Poison

Of all these cases only 9 (Beta) and 10 (Weibull) need extra arguments.  Beta needs two arguments and Weibull one.

Examples:

f1 0 1024 21 1	; Uniform (white noise)

f1 0 1024 21 6	; Gaussian

f1 0 1024 21 9 1 1 2	; Beta (note that level precedes arguments)

f1 0 1024 21 10 1 2   	; Weibull


Appendix 7:  A CSOUND QUICK REFERENCE

VALUE CONVERTERS

ftlen(x)	(init-rate args only)

int(x)	(init- or control-rate args only)

frac(x) 	Ò	Ò

dbamp(x) 	Ò	Ò

i(x)	(control-rate arg only)

abs(x)	(no rate restriction)

exp(x) 	Ò	Ò

log(x)	Ò	Ò

sqrt(x) 	Ò	Ò

sin(x) 	Ò	Ò

cos(x) 	Ò	Ò

ampdb(x)	Ò	Ò

PITCH CONVERTERS

octpch(pch)	(init- or control-rate args only)

pchoct(oct) 	Ò	Ò

cpspch(pch) 	Ò	Ò

octcps(cps) 	Ò	Ò

cpsoct(oct)	(no rate restriction)

PROGRAM CONTROL

igoto	label

tigoto	label

kgoto	label

goto	label

if	ia R ib igoto label

if	ka R kb kgoto label

if	ia R ib goto label

timout 	istrt, idur, label

MIDI CONVERTERS

ival	notnum,	veloc

icps	cpsmidi,	cpsmidib

kcps	cpsmidib

ioct	octmidi,	octmidib

koct	octmidib

ipch	pchmidi,	pchmidib

kpch	pchmidib

iamp	ampmidi	iscal[, ifn]

kaft	aftouch	iscal

kchpr	chpress	iscal

kbend	pchbend	iscal

ival	midictrl	inum

kval	midictrl	inum

SIGNAL GENERATORS

kr	line	ia, idur1, ib

ar	line	ia, idur1, ib

kr	expon 	ia, idur1, ib

ar	expon 	ia, idur1, ib

kr	linseg 	ia, idur1, ib[, idur2, ic[...]]

ar	linseg	ia, idur1, ib[, idur2, ic[...]]

kr	expseg 	ia, idur1, ib[, idur2, ic[...]]

ar	expseg 	ia, idur1, ib[, idur2, ic[...]]

kr	phasor	kcps[, iphs]

ar	phasor 	xcps[, iphs]

ir	table	indx, ifn[, ixmode][, ixoff][, iwrap]

ir	tablei	indx, ifn[, ixmode][, ixoff][, iwrap]

kr	table	kndx, ifn[, ixmode][, ixoff][, iwrap]

kr	tablei	kndx, ifn[, ixmode][, ixoff][, iwrap]

ar	table	andx, ifn[, ixmode][, ixoff][, iwrap]

ar	tablei	andx, ifn[, ixmode][, ixoff][, iwrap]

kr	oscil1	idel, kamp, idur, ifn

kr	oscil1i	idel, kamp, idur, ifn

kr	oscil	kamp, kcps, ifn[, iphs]

kr	oscili	kamp, kcps, ifn[, iphs]

ar	oscil	xamp, xcps, ifn[, iphs]

ar	oscili	xamp, xcps, ifn[, iphs]

ar	foscil	xamp, kcps, kcar, kmod, kndx, ifn[, iphs]

ar	foscili	xamp, kcps, kcar, kmod, kndx, ifn[, iphs]

      ar1 [,ar2]	loscil	 	xamp, kcps, ifn[, ibas][, imod1,ibeg1,iend1]

[, imod2,ibeg2,iend2]

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

ar	gbuzz	xamp, xcps, knh, kih, kr, ifn[, iphs]

ar	adsyn	kamod, kfmod, ksmod, ifilcod

ar	pvoc	ktimpnt, kfmod, ifilcod[, ispecwp]

ar	fof	xamp, xfund, xform, koct, kband, kris, kdur, kdec,

iolaps, ifna, ifnb, itotdur[, iphs][, ifmode]

ar	pluck 	kamp, kcps, icps, ifn, imeth [, iparm1, iparm2]

kr	rand	xamp[, iseed]

kr	randh	kamp, kcps[, iseed]

kr	randi	kamp, kcps[, iseed]

ar	rand	xamp[, iseed]

ar	randh	xamp, xcps[, iseed]

ar	randi	xamp, xcps[, iseed]


SIGNAL MODIFIERS

kr	linen	kamp, irise, idur, idec

ar	linen	xamp, irise, idur, idec

kr	linenr	kamp, irise, idec, iatdec

ar	linenr	xamp, irise, idec, iatdec

kr	envlpx	kamp, irise, idur, idec, ifn, iatss, iatdec[, ixmod]

ar	envlpx	xamp, irise, idur, idec, ifn, iatss, iatdec[, ixmod]

kr	port	ksig, ihtim[, isig]

ar	tone	asig, khp[, istor]

ar	atone	asig, khp[, istor]

ar	reson	asig, kcf, kbw[, iscl, istor]

ar	areson	asig, kcf, kbw[, iscl, istor]

krmsr,krmso,kerr,kcps	lpread 	ktimpnt, ifilcod[, inpoles][, ifrmrate]

ar	lpreson 	asig

ar	lpfreson 	asig, kfrqratio

kr	rms	asig[, ihp, istor]

nr	gain	asig, krms[, ihp, istor]

ar	balance	asig, acomp[, ihp, istor]

kr	downsamp	asig[, iwlen]

ar	upsamp 	ksig

ar	interp	ksig[, istor]

kr	integ	ksig[, istor]

ar	integ	asig[, istor]

kr	diff	ksig[, istor]

ar	diff	asig[, istor]

kr	samphold	xsig, kgate[, ival, ivstor]

ar	samphold	asig, xgate[, ival, ivstor]

ar	delayr	idlt[, istor]

delayw	asig

ar	delay	asig, idlt[, istor]

ar	delay1	asig[, istor]

ar	deltap	kdlt

ar	deltapi	xdlt

ar	comb	asig, krvt, ilpt[, istor]

ar	alpass	asig, krvt, ilpt[, istor]

ar	reverb	asig, krvt[, istor]

OPERATIONS USING SPECTRAL DATA TYPES

dsig	octdown	xsig, iocts, isamps[, idisprd]

wsig	noctdft	dsig, iprd, ifrqs, iq[, ihann, idbout, idsines]

wsig	specaddm	wsig1, wsig2[, imul2]

wsig	specdiff	wsigin

wsig	specscal	wsigin, ifscale, ifthresh

wsig	spechist	wsigin

wsig	specfilt	wsigin, ifhtim

koct	specptrk 	wsig, inptls, irolloff, iodd[, interp, ifprd, iwtflg]

ksum	specsum 	wsig[, interp]

specdisp	wsig, iprd[, iwtflg]

SENSING & CONTROL

ktemp	tempest	kin, iprd, imindur, imemdur, ihp, ithresh, ihtim, ixfdbak,

istartempo, ifn[, idisprd, itweek]

kx, ky	xyin	iprd, ixmin, ixmax, iymin, iymax[, ixinit, iyinit]

tempo	ktempo, istartempo

SIGNAL INPUT & OUTPUT

a1	in

a1, a2	ins

a1, a2, a3, a4	inq

a1	soundin	ifilcod[, iskptim][, iformat]

a1, a2	soundin	ifilcod[, iskptim][, iformat]

a1, a2, a3, a4	soundin	ifilcod[, iskptim][, iformat]

out	asig

outs1	asig

outs2	asig

outs	asig1, asig2

outq1	asig

outq2 	asig

outq3	asig

outq4	asig

outq	asig1, asig2, asig3, asig4

a1, a2, a3, a4	pan	asig, kx, ky, ifn[, imode][, ioffset]

kdump	ksig, ifilname, iformat, iprd

kdump2	ksig1, ksig2, ifilname, iformat, iprd

kdump3	ksig1, ksig2, ksig3, ifilname, iformat, iprd

kdump4	ksig1, ksig2, ksig3, ksig4, ifilname, iformat, iprd

SIGNAL DISPLAY

print	iarg[, iarg,...]

display	xsig, iprd[, inprds][, iwtflg]

dispfft	xsig, iprd, iwsiz[, iwtyp][, idbout][, iwtflg]