Opcodes of CsoundAV

ORCHESTRA OPCODES

by Gabriel Maldonado
gabriel@musicaverticale.net
http://csounds.com/maldonado

Single slider control

idest midic7 ictlno, imin, imax [, ifn]
kdest midic7 ictlno, kmin, kmax [, ifn]

idest midic14 ictlno1, ictlno2, imin, imax [, ifn]
kdest midic14 ictlno1, ictlno2, kmin, kmax [, ifn]

idest midic21 ictlno1, ictlno2, ictlno3, imin, imax [, ifn]
kdest midic21 ictlno1, ictlno2, ictlno3, kmin, kmax [, ifn]

idest ctrl7 ichan, ictlno, imin, imax [,ifn]
kdest ctrl7 ichan, ictlno, kmin, kmax [,ifn]

idest ctrl14 ichan, ictlno1, ictlno2, imin, imax [,ifn]
kdest ctrl14 ichan, ictlno1, ictlno2, kmin, kmax [,ifn]

idest ctrl21 ichan, ictlno1, ictlno2, ictlno3, imin, imax [,ifn]
kdest ctrl21 ichan, ictlno1, ictlno2, ictlno3, kmin, kmax [,ifn]

DESCRIPTION

Return precise signal from a MIDI slider.

INITIALIZATION

idest - output signal
ichan - MIDI channel (1-16). In (i)ctrl14 and (i)ctrl21 all the controllers used in an opcode instance must be of the same channel
ictlno - midi controller number (1-127)
ictlno1 - most-significant byte controller number (1-127)
ictlno2 - in midic14: less-significant byte controller number (1-127); in midic21: mid-significant byte controller number (1-127)
ictlno3 - less-significant byte controller number (1-127)
imin - user-defined minimum floating-point value of output
imax - user-defined maximum floating-point value of output
ifn (optional) - table to be read when indexing is required. Table must be normalized. Output is scaled according to max and min val.

PERFORMANCE

kdest - output signal
kmin - user-defined minimum floating-point value of output
kmax - user-defined maximum floating-point value of output

midic7 (i and k rate 7 bit midi control) allows floating point 7 bit midi signal scaled with a minimum and a maximum range. They also allow optional non-interpolated table indexing.
In midic7 minimum and maximum values can be varied at krate.

midic14 (i and k-rate 14 bit midi control) does the same as the above with 14 bit precision.

midic21 (i and k rate 21 bit midi control) do the same as the above with 21 bit precision.

midic14 and midic21 can use optional interpolated table indexing. They require two or three midi controllers as input.

Warnig! Don't use (i)midicXX opcodes within a sco-activated i-statement or Csound will crash. Instruments containing (i)midicXX opcodes can be only activated by a MIDI note-on message. Use (i)ctrlXX opcodes if you need to include them in a sco-oriented instrument instead.

ctrl7, ctrl14, ctrl21 are very similar to midicXX opcodes the only differeces are:

ctrlXX UGs can be included in sco-oriented instruments without Csound crashes.
They need the addictional parameter ichan containing the MIDI channel of the controller.

MIDI channel is the same for all the controller used in a single (i)ctrl14 or (i)ctrl21 opcode.

Single slider control initialization

initc7 ichan, ictlno, ivalue
initc14 ichan, ictlno1, ictlno2, ivalue
initc21 ichan, ictlno1, ictlno2, ictlno3, ivalue

DESCRIPTION

Initializes MIDI controller ictlno with ivalue

INITIALIZATION

ichan - midi channel (1-16)
ictlno - controller number (initc7)
ictlno1 - MSB controller number
ictlno2 - in initc14 LSB controller number; in initc21 Medium Significant Byte controller number
ictlno3 - LSB controller number
ivalue - floating point value (must be within 0 to 1)

initc7, initc14, initc21 can be used togheter with both (i)midicXX and

(i)ctrlXX opcodes for initializing the first controllers' value.
Ivalue argument must be set with a number within 0 to 1. An error occurs if it is not.

Use the following formula to set ivalue according with (i)midicXX and (i)ctrlXX min and max range:

ivalue = (initial_value - min) / (max - min)

MIDI Note Generators

noteon ichn, inum, ivel
noteoff ichn, inum, ivel
noteondur ichn, inum, ivel, idur
noteondur2 ichn, inum, ivel, idur

DESCRIPTION

send note-on and note-off messages to the MIDI OUT port.
(warning! these opcodes have been renamed in to avoid namespace pollution. Before noteon was ion, noteoff was ioff, noteondur was iondur and noteondur2 was iondur2).

INITIALIZATION

ichn - MIDI channel number (1-16)
inum - note number (0-127)
ivel - velocity (0-127)
idur - duration in seconds beetween noteon and relative noteoff messages

PERFORMANCE

noteon (i-rate note on) and ioff (i-rate note off) are the simplest MIDI OUT opcodes.
noteon sends a MIDI noteon message to MIDI OUT port, and ioff sends a noteoff message.
A noteon opcode must always be follwed by an noteoff with the same channel and number inside the same instrument, otherwise the note will play endlessly.

noteon and noteoff are useful only when introducing a timout statement to play a non zero duration MIDI note. For most purposes it is better to use noteondur and noteondur2.

noteondur and noteondur2 (i-rate note on with duration) send a note-on and a note-off MIDI message both with the same channel, number and velocity. A note-off message is sent after idur seconds are elapsed by the time iondur was activated.

noteondur differs from noteondur2 in that noteondur truncates note duration when current instrument is deactivated by score or by realtime playing, whereas noteondur2 will extend performance time of current instrument until idur seconds have elapsed.

In realtime playing it is suggested to use noteondur also for undefined durations, giving a large idur value.

Any number of noteondur or noteondur2 opcodes can appear in the same Csound instrument, allowing chords to be played by a single instr.

Streams of MIDI Notes

moscil kchn, knum, kvel, kdur, kpause
midion kchn, knum, kvel

DESCRIPTION

Send stream of note-on and note-off messages to the MIDI OUT port.
(Note that midion opcode was previously named kon. This opocode has been renamed to avoid namespace pollution).

PERFORMANCE

kchn - MIDI channel number (1-16)
knum - note number (0-127)
kvel - velocity (0-127)
kdur - note duration in seconds
kpause - pause duration after each noteoff and before new note in seconds

moscil and kon are the most powerful MIDI OUT opcodes.

moscil (midi oscil) plays a stream of notes of kdur duration. Channel, pitch, velocity, duration and pause can be controlled at k-rate, allowing very complex algorythmically generated melodic lines.
When current instrument is deactivated, the note played by current instance of moscil is forcely truncated.

midion (before called kon i.e. k-rate note on) plays MIDI notes with current kchn, knum and kvel. These arguments can be varied at k-rate. Each time the MIDI converted value of any of these arguments changes, last MIDI note played by current instance of kon is immediately turned off and a new note with the new argument values is activated.
This opcode, as well as moscil, can generate very complex melodic textures if controlled by complex k-rate signals.

Any number of moscil or kon opcodes can appear in the same Csound instrument, allowing a counterpoint-style polyphony within a single instrument.

MIDI Channel Message Output

outic ichn, inum, ivalue, imin, imax
outkc kchn, knum, kvalue, kmin, kmax
outic14 ichn, imsb, ilsb, ivalue, imin, imax
oukc14 kchn, kmsb, klsb, kvalue, kmin, kmax

outipb ichn, ivalue, imin, imax
outkpb kchn, kvalue, kmin, kmax
outiat ichn, ivalue, imin, imax
outkat kchn, kvalue, kmin, kmax
outipc ichn, iprog, imin, imax
outkpc kchn, kprog, kmin, kmax

outipat ichn, inotenum, ivalue, imin, imax
outkpat kchn, knotenum, kvalue, kmin, kmax

DESCRIPTION

Send a single Channel message to the MIDI OUT port.

INITIALIZATION AND PERFORMANCE

ichn, kchn - MIDI channel number (1-16)
inum, knum - controller number (0-127 for examp. 1 = ModWheel; 2 = BreathControl etc.)
ivalue, kvalue - floating point value
imin, kmin - minimum floating point value (converted in midi integer value 0)
imax, kmax - maximum floating point value (converted in midi integer value 127 (7 bit) or 16383 (14 bit))
imsb, kmsb - most significant byte controller number when using 14 bit parameters
ilsb, klsb - less significant byte controller number when using 14 bit parameters
iprog, kprog - program change number in floating point
inotenum, knotenum - MIDI note number (used in polyphonic aftertouch messages)

ioutc and koutc (i and k-rate midi controller output) send controller messages to MIDI OUT device.

ioutc14 and koutc14 (i and k-rate midi 14 bit controller output) send a pair of controller messages. These opcodes can drive 14 bit parameters on MIDI instruments that recognize them. The first control message contains the most significant byte of i(k)value argument while the second message contains the less significant byte.
i(k)msb and i(k)lsb are the number of the most and less significant controller.

ioutpb and koutpb (i and k-rate pitch bend output) send pitch bend messages.

ioutat and koutat (i and k-rate aftertouch output) send aftertouch messages.

ioutpc and koutpc (i and k-rate program change output) send program change messages.

ioutpat and koutpat (i and k-rate polyphonic aftertouch output) send polyphonic aftertouch messages. These opcodes can drive a different value of a parameter for each note currently active. They work only with MIDI instruments which recognize them.

N.B. All these opcodes can scale the i(k)value floating-point argument according with i(k)max and i(k)min values. For example, setting i(k)min = 1.0 and i(k)max = 2.0, when i(k)value argument receives a 2.0 value, the opcode will send a 127 value to MIDI OUT device, while when receiving a 1.0 it will send a 0 value.

I-rate opcodes send their message once during instrument initialization.
K-rate opcodes send a message each time the MIDI converted value of argument i(k)value changes.

MIDI Realtime Message Output

mclock ifreq
mrtmsg imsgtype

DESCRIPTION

Send System Realtime messages to the MIDI OUT port.

INITIALIZATION

ifreq - clock message frequency rate in Hz

imsgtype - type of real-time message:

1 sends a START message (0xFA);
2 sends a CONTINUE message (0xFB);
0 sends a STOP message (0xFC);
-1 sends a SYSTEM RESET message (0xFF);
-2 sends an ACTIVE SENSING message (0xFE)

PERFORMANCE

mclock (midi clock) sends a MIDI CLOCK message (0xF8) every 1/ifreq seconds. So ifreq is the frequency rate of CLOCK messages in Hz.

mrtmsg (midi realtime message) sends a realtime message once, in init stage of current instrument. imsgtype parameter is a flag to indicate the message type (see above, in ARGUMENTS description).

Duration Extension of MIDI Notes

xtratim iextradur
kflag release

DESCRIPTION

Extend the duration of realtime generated events and handle their extra life.

INITIALIZATION

iextradur - additional duration of current instrument instance

PERFORMANCE

xtratim extends current MIDI-activated note duration of iextradur seconds after the corresponding note-off message has deactivated current note itself.
This opcode has no output arguments.

release outputs current note state. If current note is in the release stage (i.e. if its duration has been exetended with xtratim opcode and if it has only just deactivated), kflag output argument is set to 1, else (in sustain stage of current note) is set to 0.

These two opcodes are useful for implementing complex release-oriented envelopes.

Example:

        instr  1       ;allows complex ADSR envelope with MIDI events

inum    notnum

icps    cpsmidi

iamp    ampmidi 4000

;############## complex envelope section ##############

        xtratim 1       ;extra-time, i.e. release dur

krel    init    0

krel    release         ;outputs release-stage flag (0 or 1 values)

if      (krel > .5) kgoto  rel  ;if in relase-stage goto relase section

;************ attack and sustain section ***********

kmp1    linseg  0,.03,1,.05,1,.07,0,.08,.5,4,1,50,1

kmp     =       kmp1*iamp

        kgoto   done

;************ release section **********************

rel:

kmp2    linseg  1,.3,.2,.7,0

kmp     =       kmp1*kmp2*iamp

done:

;###################################################

a1      oscili  kmp, icps, 1

        out     a1

        endin

Wrapping Signals Around

idest wrap isig, ilow, ihigh
kdest wrap ksig, klow, khigh
adest wrap asig, klow, khigh

idest mirror isig, ilow, ihigh
kdest mirror ksig, klow, khigh
adest mirror asig, klow, khigh

DESCRIPTION

Wraps the signal in various ways (similar to limit opcode by Robin Whittle).

INITIALIZATION - PERFORMANCE

xdest - output signal
xsig - input ignal
xlow - low threshold
xhigh - high threshold

mirror "reflects" the signal that exceeds low and high thresholds.

wrap wraps-around the signal that exceeds low and high thresholds.

These opcodes are useful in several situations, such as for table indexing and for clipping and modeling irate, krate or arate signals.
wrap are also useful for wrapping-around tables data when maximum index is not a power of two (see table and tablei).
Another use of wrap is in cyclical event repeating with arbirary cycle length.

ftlen2(x)

DESCRIPTION

this function is the same as ftlen( ) but operates also with deferred-allocation function size with GEN1 and GEN22 (see them for more informations).

nsamp(x)

DESCRIPTION

This function returns the number of samples effectively loaded by GEN01 or GEN22 from a file. This function is useful when table length is a power of two (i.e. not deferred allocation is used) larger than the file sample number of the file.

ftsr(x)

DESCRIPTION

This function returns the sampling-rate of a GEN01 or GEN22 generated table. The sampling-rate is determined from the header of the original file. If the original file has not header, ftsr returns 0.

loscil2

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

DESCRIPTION

Read sampled sound (mono or stereo) from a table of 16-bit integer samples, with optional sustain and release looping. Uses 16-bit integer table (see GEN 22).

INITIALIZATION

See loscil for details.

PERFORMANCE

See loscil for details.

N.B.

This opcode is almost identical to loscil, the only difference is loscil2 uses 16-bit integer function table (see GEN 22) for storing samples, increasing realtime performance and reducing sample-memory consumption in half.

WARNING! You MUST use only GEN 22 to allow this opcode operates correctly!

fof3

ar fof3 xamp, xfund, xform, koct, kband, kris, kdur, kdec, iolaps, ifna, ifnb, itotdur, kphs, kgliss

DESCRIPTION

Audio output is a succession of sinusoid bursts initiated at frequency xfund with a spectral peak at xform. For xfund above 25 Hz these bursts produce a speech-like formant with spectral characteristics determined by the k-input parameters. For lower fundamentals this generator provides a special form of granular synthesis.

fof3 is identical to fof, except that the optional arguments iphs and iform are required k-rate arguments, kphs and kgliss, allowing granular synthesis and grain glissandi.

INITIALIZATION and PERFORMANCE

see fof, fof2 and fog

N.B.

fof3 is identical to fof2, except that:

1) samples of ifna are lineary interpolated to icrease sound quality and to lower distortion
2) ifna argument must refer to a GEN22 generated table (16-bit integers stored in RAM). This halves RAM need for sample-functions.

See fof, fof2 and fog for more informations.

GEN22

Transfer data from a soundfile into a function table using 16-bit integers for storing it in RAM.

f # time size -22 filcod skiptime format channel

for more information see GEN 01.

This gen-function is almost identical to GEN01. The only difference is GEN22 can only read 16 bit integer samples in mono or stereo and stores them in RAM keeping 16-bit integer format This halves RAM need. Very useful for LONG samples.

For now GEN22 can operate only with loscil2, lposcint and fof3 opcodes . You must always suppress normalization by using a negative GEN number, otherwise you will obtain a meaningless sequence of 1 , -1 and 0 integer values!

WARNING! The only opcodes which can use GEN22-generated functions are loscil2, lposcint and fof3. You must rescale the output of loscil2 and fof3 opcodes, when upgrading instruments written with the older opcodes (i.e. loscil and fof2) otherwise they could surpass the range limit of output.

Don’t attempt to use GEN22 with any other opcode (for now).

printk2

printk2 kvar [, numspaces]

INITIALIZATION

numspaces - number of space characters printed before the value of kvar

PERFORMANCE

kvar - signal to be printed

Derived from Robin Whittle's printk, prints a new value of kvar each time kvar changes. Useful for monitoring MIDI control changes when using sliders.

Warning! don't use this opcode with normal, continuously variant k-signals, because it can hang the computer, as the rate of printing is too fast.

lowres, lowresx

ar lowres asig, kcutoff, kresonance [,istor]

ar lowresx asig, kcutoff, kresonance [, inumlayer, istor]

Warning: lpres and lpresx have been renamed to lowres and lowresx

DESCRIPTION

lowres is a resonant lowpass filter.

lowresx is equivalent to more layer of lpres, with the same arguments, serially connected.

INITIALIZATION

inumlayer - number of elements of lpresx stack. Default value is 4. Maximum value is 10
istor - initial disposition of internal data space.

A zero value will clear the space; a non-zero value will allow previous information to remain. The default value is 0.

PERFORMANCE

ar - output signal
asig - input signal
kcutoff - filter cutoff frequency point
kresonance - resonance amount

lowres is a resonant lowpass filter derived from a Hans Mikelson´s orchestra.

This implementation is very much faster than implementing it in Csound language, and it allows kr lower than sr. kcutoff is not in cps and kresonance is not in dB, so experiment for finding best results.

lowresx is equivalent to more layer of lpres, with the same arguments, serially connected. Using a stack of more filters allows a sharper freqency cutoff. It is very faster than using more lpres instances in Csound orchestra, because only one initialization and 'k' cycle are needed at time, and the audio loop falls enterely inside the cache memory of processor.

tonex, atonex, resonx

ar tonex asig, khp[, inumlayer, istor]

ar atonex asig, khp[, inumalayer, istor]

ar resonx asig, kcf, kbw[, inumlayer, iscl, istor]

INITALIZATION

inumlayer - number of elements of filter stack. Default value is 4. Maximum value is 10
isig - some as tone, atone and reson
istor - some as tone, atone and reson
iscl - some as reson

PERFORMANCE

ar - output signal
asig - input signal
khp - some as tone, atone
kcf - some as reson
kbw - some as reson

tonex, atonex and resonx are equivalent to more layer of tone, atone and reson, with the same arguments, serially connected.
Using a stack of more filters allows a sharper frequency cutoff.
They are very faster than using more instances in Csound orchestra of old opcodes,because only one initialization and 'k' cycle are needed at time, and the audio loop falls enterely inside the cache memory of processor.

poscil and lposcil

ar poscil xamp, xcps, ift [,iphs]
kr poscil kamp, kcps, ift [,iphs]
ar poscil3 kamp, kcps, ift [,iphs]
kr poscil3 kamp, kcps, ift [,iphs]

ar lposcil kamp, kfreqratio, kloop, kend, ift [,iphs]
ar lposcil3 kamp, kfreqratio, kloop, kend, ift [,iphs]

ar lposcila aamp, kfreqratio, kloop, kend, ift [,iphs]
ar1, ar2 lposcilsa aamp, kfreqratio, kloop, kend, ift [,iphs]
ar1, ar2 lposcilsa2 aamp, kfreqratio, kloop, kend, ift [,iphs]

ar lposcint kamp, kfreqratio, kloop, kend, ift [,iphs]
ar lposcinta aamp, kfreqratio, kloop, kend, ift [,iphs]
ar1, ar2 lposcintsa aamp, kfreqratio, kloop, kend, ift [,iphs]
ar1, ar2 lposcintsa2 aamp, kfreqratio, kloop, kend, ift [,iphs]

(Note that poscil and lposcil opcode were previously named posc and lposc. These opocodes have been renamed to avoid namespace pollution. poscil3 and lposcil3 are cubic interpolated versions of poscil and lposcil by John Fitch).

poscil can be used with tables of non-power-of-two length

INITALIZATION

ift - function table number

iphs - initial phase (in samples)

PERFORMANCE

ar - output signal
kamp, aamp - amplitude
kcps - frequency
kfreqratio - multiply factor of table frequency (for example: 1 = original frequency, 1.5 = a fifth up , .5 = an octave down)
kloop - loop point (in samples)
kend - end loop point (in samples)

poscil (precise oscillator) is the same as oscili but allows hugely more precise frequency control (especially when using long tables and low frequency values). It uses floating-point table indexing instead of integer math, differently by oscil and oscili. It is only a bit slower than oscili.

lposcil (loop oscillator) allows to vary in k rate the starting and ending point of a sample contained in a table. This can be useful when reading samples loop of a wavetable whose repeat speed can be varied during the performance.

lposcila is the same as lposcil, but has an audio-rate amplitude argument (instead of k-rate) to allow fast envelope transients.

lposcilsa is the same as lposcila, but works with stereo files loaded with GEN1.

lposcilsa2 is the same as lposcilsa, but no interpolation is implemented and only works with integer kfreqratio values. Much faster than lposcilsa, it is mainly intended to be used with kfreqratio = 1, being in this case a fast substitute of soundin, since the soundfile must be entirely loaded in memory.

lposcint is the same as lposcil, but read integer stored sample tables (GEN22) to reduce RAM memory needs.

lposcinta is the same as lposcint, but has an audio-rate amplitude argument (instead of k-rate) to allow fast envelope transients.

lposcintsa is the same as lposcinta, but works with stereo files loaded with GEN22.

lposcintsa2 is the same as lposcintsa, but no interpolation is implemented and only works with integer kfreqratio values. Much faster than lposcintsa, it is mainly intended to be used with kfreqratio = 1, being in this case a fast substitute of soundin, since the soundfile must be entirely loaded in memory.

wguide1 and wguide2

ar wguide1 asig, xfreq, kcutoff, kfeedback;
ar wguide2 asig, xfreq1, xfreq2, kcutoff1, kcutoff2, kfeedback1, kfeedback2

(Note that wguide1 and wguide2 were previously named physic1. and physic2. These opocodew have been renamed to avoid namespace pollution).

DESCRIPTION

Simple waveguide blocks (see picture)

PERFORMANCE

wguide1 is the most elemental waveguide model consisting of one delay line and one first-order lowpass filter.

wguide2 is a model of beaten plate consisting of two parallel delay lines and two first-order lowpass filters. The two feedabak lines are mixed and sent to the delay again each cycle.

asig is the input of excitation noise, xfreq the frequency (i.e. the inverse of delay time), kcutoff is the filter cutoff frequency in Hz and kfeedback is the feedback factor.

Implementing waveguide algoritms as opcodes, instead of as orc instr, allows the user to set kr different than sr, allowing better performance particulary when using real-time. (see also the block diagram included in 'physic.bmp' picture)

trigger

kout trigger ksig, kthreshold, kmode
(previously called trig).

DESCRIPTION

informs when a krate signal crosses a threshold

PERFORMANCE

kout - output signal (a stream of zeroes with some 1)
ksig - input signal
kthreshold - trigger threshold
kmode - can be 0 , 1 or 2

Normally trigger outputs zeroes: only each time ksig crosses kthreshold trigger outputs a 1.

There are three modes of using trigger:

kmode = 0 - (down-up) trigger outputs a 1 when current value of ksig is higher than kthreshold whereas old value of ksig was equal or lower than kthreshold

kmode = 1 - (up-down) trigger outputs a 1 when current value of ksig is lower than kthreshold whereas old value of ksig was equal or higher than kthreshold

kmode = 2 - (both) trigger outputs a 1 in both the two previous cases.

midiin

kstatus, kchan, kdata1, kdata2 midiin

DESCRIPTION

Returns a generic midi message received by the midi in port

PERFORMANCE

kstatus - the type of midi message. Can be:

128 (note off),
144 (note on),
160 (polyphonic aftertouch),
176 (control change),
192 (program change),
208 (channel aftertouch),
224 (pitch bend)

or 0 if no midi message are pending in the MIDI IN buffer.

kchan - midi channel (1-16)
kdata1, kdata2 - message-dependent data values

midiin has no input arguments, because it reads at the midi in port implicitly. It works at k-rate. Normally (i.e. when no messages are pending) kstatus is zero, only each time midi data are present in the midi in buffer, kstatus is set to the type of the relative messages.

midiout

midiout kstatus, kchan, kdata1, kdata2

DESCRIPTION

sends a generic midi message to the midi out port

PERFORMANCE

kstatus - the type of midi message. Can be:

128 (note off),
144 (note on),
160 (polyphonic aftertouch),
176 (control change),
192 (program change),
208 (channel aftertouch),
224 (pitch bend)
or 0 when no midi messages must be sent to the MIDI OUT port.

kchan - midi channel (1-16)
kdata1, kdata2 - message-dependent data values

midiout has not output arguments, because it sends the message to the midi out port implicitly. It works at k-rate. It sends a midi message only when kstatus is different than zero.

Warning! Normally kstatus should be set to 0, only when the user intend to send a midi message, it can be set to the corresponding message type number.

midion2

midion2 kchn, knum, kvel, ktrig

DESCRIPTION

sends note on and off messages to the midi out port when triggered by a value different than zero.
(Note that midion2 opcode was previously named kon2. This opocode has been renamed to avoid namespace pollution).

PERFORMANCE

kchn - midi channel
knum - midi note number
kvel - note velocity
ktrig - trigger input signal (normally 0)

Similary to midion, this opcode sends note-on and note-off messages to the midi out port, but midion2 does it only when ktrig is different than zero. This opcode is thinked to work toghether with the output of the trig opcode.

nrpn

nrpn kchan, kparmnum, kparmvalue

DESCRIPTION

sends a nprn (Non Registered Parameter Number) message to the midi out port each time one of the input arguments changes.

PERFORMANCE

kchan - midi channel
kparmnum - number of NRPN parameter
kparmvalue - value of NRPN parameter

This opcode sends new message when the MIDI translated value of one of the input arguments changes. It operates at k-rate. Useful with the midi instruments that recognize NRPNs (for example with the newest sound-cards with internal midi synthesizer such as SB AWE32, AWE64, GUS etc. in which each patch parameter can be changed during the performance via NRPN)

mdelay

mdelay kstatus, kchan, kdata1, kdata2, kdelay

DESCRIPTION

A midi delay

PERFORMANCE

kstatus - status byte of midi message to be delayed
kchan - midi channel (1-16)
kdata1 - first midi data byte
kdata2 - second midi data byte
kdelay - delay time in seconds

This opcode grabs a midi message each time kstatus is different than zero and sends it to the midi out port after kdelay seconds.
This opcode is useful to implement midi delays.
More instance of this opcode can be present in the same instr with different argument values, so complex and colourful midi echoes can be implemented. Furthermore, the delay can be changed at k-rate.

loopseg, lpshold

ksig loopseg kfreq, ktrig, initphs, kvalue0, ktime0, kvalue1, ktime1 [, ... , kvalueN, ktimeN]
ksig lpshold kfreq, ktrig, initphs, kvalue0, ktime0, kvalue1, ktime1 [, ... , kvalueN, ktimeN]

ksig loopsegp kphase, kvalue0, ktime0, kvalue1, ktime1 [, ... , kvalueN, ktimeN]
ksig lpsholdp kphase, kvalue0, ktime0, kvalue1, ktime1 [, ... , kvalueN, ktimeN]

DESCRIPTION

Generate control signal consisiting of linear segments delimited by two or more specified points. The entire envelope can be looped at time-variant rate. Each segment coordinate can also be varied at k-rate.

INITIALISATION

initphs - initial phase (in the 0 to 1 range)

PERFORMANCE

ksig - output signal
kfreq - repeat rate in Hz or fraction of Hz
ktrig - if non-zero, retriggers the envelope from start (see trigger opcode), before the envelope cycle is completed
kvalue0...kvalueN - values of points
ktime0...ktimeN - times of points expessed in fraction of a cycle

loopseg opcode is similar to linseg, but the entire envelope is looped at kfreq rate. Notice that times are not expressed in seconds but in fraction of a cycle. Actually each duration represent is proportional to the other, and the entire cycle duration is proportional to the sum of all duration values. The sum of all duration is then rescaled according to kfreq argument. For example, considering an envelope made up of 3 segments, each segment having 100 as duration value, their sum will be 300. This value represents the total duration of the envelope, and is actually divided into 3 equal parts, a part for each segment. Actually, the real envelope duration in seconds is determined by kfreq. Again, if the envelope is made up of 3 segments, but this time the first and last segments have a duration of 50, whereas the central segment has a duration of 100 again, their sum will be 200. This time 200 represent the total duration of the 3 segments, so the central segment will be twice as long as the other segments. Notice that, differently from the linseg family, the last argument is a time, not a value. The last time represents the interval between last value and the first value when repeating the loop. The initial X coordinate of the envelope can be arbitrarily started with a point different than zero, by setting the initphs argument.

All parameters can be varied at k-rate.

Negative frequency values are allowed, reading the envelope backward.

lpshold is similar to loopseg, but can generate only horizontal segments, i.e. holds values for each time interval placed beetween ktimeN and ktimeN+1. It can be useful, among other things, for melodic control, like old analog sequencers.

loopsegp and lpsholdp (the final 'p' stands for 'phase') are similar to loopseg and lpshold, the only difference is that, instead of frequency, it is required a time-variant phase. If you use a phasor to get the phase value, you will have a behavior identical to loopseg and lpshold, but interesting results can be achieved when using phases having non-linear motions, making loopsegp and lpsholdp more powerful and general than loopseg and lpshold.

expsega

asig expsega ia, idur1, ib[, idur2, ic[...]]

DESCRIPTION

An exponential segment generator operating at a-rate. This unit is almost identical to expseg, but very more precise when defining segments with very short duration (i.e. in percussive attack phase) at audio-rate.

Note that old expseg opcode does not operate correctly at audio rate when segments are shorter than a k-period.

INITIALISATION

ia - starting value. Zero is illegal.
ib, ic, etc. - value after idur1 seconds, etc. must be non-zero and must agree in sign with ia.
idur1 - duration in seconds of first segment.

A zero or negative value will cause all initialization to be skipped.

idur2, idur3, etc. - duration in seconds of subsequent segments.
A zero or negative value will terminate the initialization process with the preceding point, permitting the last-defined line or curve to be continued indefinitely in performance. The default is zero.

PERFORMANCE

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.

Perry Cook opcodes (DEPRECATED for NOW)

(derived by a Michael Gogins Csound version which supports an external library of opcodes. The 'perry_toolkit.opc' file must be present in the same directory of CsoundAV executable in order to enable these opcodes)

list of opcodes:

marimba
vibraphone
agogobell
plucked
mandolin
clarinet
flute
brass
bowed
rhodes
wurlitzer
tubularbell
heavymetal
percussiveflute
hammond
fmvoices
minimoog
voiceformant

example:

ar marimba xcps, xamp, xconstatus, xcondata1, xcondata2, xmodwheel

Audio output is a physical model of the named instrument based on waveguide synthesis,

frequency modulation synthesis, or modal synthesis.

Initialization

There are no specifically initialization-time variables.

Performance

xcps - Frequency in cycles per second.
xamp - Amplitude multiplier.
xconstatus - MIDI control message status byte. Meaning depends upon opcode, but analogous to corresponding MIDI patch.
xcondata1 - MIDI control message data byte 1. Meaning depends upon opcode, but analogous to corresponding MIDI patch.
xcondata2 - MIDI control message data byte 2. Meaning depends upon opcode, but analogous to corresponding MIDI patch.
xmodwheel - MIDI modulation wheel value. Meaning depends upon opcode, but analogous to corresponding MIDI patch.

marimjpff

the marimba described in the 3.47 manual by John Fitch (ranamed to avoid name-conflict with original Perry Cook algorythms included in the external library).

Banks of sliders

slider8, slider16, slider32, slider64
slider8f, slider16f, slider32f, slider64f
s16b14, s32b14

SYNTAX

k1,k2,k3,k4,k5,k6,k7,k8 slider8 ichan, ictlnum1, imin1, imax1, init1, ifn1, .... , \
ictlnum8, imin8, imax8, init8, ifn8

k1, ... , k16 slider16 ichan, ictlnum1, imin1, imax1, init1, ifn1, .... , \
ictlnum16, imin16, imax16, init16, ifn16

k1, ... , k32 slider32 ichan, ictlnum1, imin1, imax1, init1, ifn1, .... , \
ictlnum32, imin32, imax32, init32, ifn32

k1, ... , k64 slider64 ichan, ictlnum1, imin1, imax1, init1, ifn1, .... , \
ictlnum64, imin64, imax64, init64, ifn64

k1,k2,k3,k4,k5,k6,k7,k8 slider8f ichan, ictlnum1, imin1, imax1, init1, ifn1, icutoff1, .... , \
ictlnum8, imin8, imax8, init8, ifn8, icutoff8

k1, ... , k16 slider16f ichan, ictlnum1, imin1, imax1, init1, ifn1, icutoff1, .... , \
ictlnum16, imin16, imax16, init16, ifn16, icutoff16

k1, ... , k32 slider32f ichan, ictlnum1, imin1, imax1, init1, ifn1, icutoff1, .... , \
ictlnum32, imin32, imax32, init32, ifn32, icutoff32

k1, ... , k64 slider64f ichan, ictlnum1, imin1, imax1, init1, ifn1, icutoff1, .... , \
ictlnum64, imin64, imax64, init64, ifn64, icutoff64

i1, ... , i8 slider8 ichan, ictlnum1, imin1, imax1, ifn1, .... , \
ictlnum8, imin8, imax8, ifn8

i1, ... , i16 slider16 ichan, ictlnum1, imin1, imax1, ifn1, .... , \
ictlnum16, imin16, imax16, ifn16

i1, ... , i32 slider32 ichan, ictlnum1, imin1, imax1, ifn1, .... , \
ictlnum32, imin32, imax32, ifn32

i1, ... , i64 slider64 ichan, ictlnum1, imin1, imax1, ifn1, .... , \
ictlnum64, imin64, imax64, ifn64

i1, ... , i16 s16b14 ichan, ictlno_msb1, ictlno_lsb1, imin1, imax1, initvalue1, ifn1, ....., \
ictlno_msb16, ictlno_lsb16, imin16, imax16, initvalue16, ifn16

i1, ... , i16 is16b14 ichan, ictlno_msb1, ictlno_lsb1, imin1, imax1, ifn1, .......... \
ictlno_msb16, ictlno_lsb16, imin16, imax16, ifn16

i1, ... , i32 s32b14 ichan, ictlno_msb1, ictlno_lsb1, imin1, imax1, initvalue1, ifn1, ....., \
ictlno_msb32, ictlno_lsb32, imin32, imax32, initvalue32, ifn32

i1, ... , i32 s32b14 ichan, ictlno_msb1, ictlno_lsb1, imin1, imax1, ifn1, .......... \
ictlno_msb32, ictlno_lsb32, imin32, imax32, ifn32

DESCRIPTION

MIDI slider control banks

INITIALIZATION

i1 ... i64 - output values
ichan - midi channel (1-16)
ictlnum1 ... ictlnum64 - midi control number
ictlno_msb1 .... ictlno_msb32 - midi control number (most significant byte)
ictlno_lsb1 .... ictlno_lsb32 - midi control number (less significant byte)
imin1 ... imin64 - minimum values for each controller
imax1 ... imax64 - maximum values for each controller
init1 ... init64 - inital value for each controller
ifn1 ... ifn64 - function table for conversion for each controller
icutoff1 ... icutoff64 - low pass filter frequency cutoff for each controller

PERFORMANCE

k1 ... k64 - output values

isliderN, sliderN and sliderNf are banks of MIDI controller (useful together with VMCI and when using midi mixer such as KAWAI MM-16 or others for changing whatever sound parameter in realtime).

The raw midi control messages at the input port are converted to agree with iminN and imaxN, and an initial value can be set. Also an optional non-interpolated function table with a custom translation curve is allowed, useful for enabling exponential response curves.

When no function table translation is required, set the ifnN value to 0, else set ifnN to a valid function table number.

When table translation is enabled (i.e. setting ifnN value to a non-zero number referring to an already allocated function table), initN value should be set equal to iminN or imaxN value, else the initial output value will not be the same as specified in initN argument.

slider8 allows a bank of 8 different midi control message numbers, slider16 does the same with a bank of 16 controls, and so on.

sliderNf filter the signal before output for eliminating discontinuities due to the low resolution of the MIDI (7 bit); the cutoff frequency can be set separately for each controller (suggested range: .1 to 5 cps). Warning! sliderNf opcodes do not output the required initial value immediately, but only after some k-cycle because the filter slightly delays the output.

As the input and output arguments are many, you can split the line using '\' (backslash) character (new in 3.47 version) to improve the readability. Using these opcodes is quite more efficient than using the separate ones (ctrl7 and ktone) when more controllers are required.

In isliderN there is not an initial-value input argument because the output is get directly from current status of internal controller array of Csound.

isNb14 and sNb14 opcodes are the 14-bit versions of these banks of controllers.

Power of two related

powoftwo(x)
logbtwo(x)

powoftwo() function returns 2 ^ x and allows positive and negatives numbers as argument. The range of values admitted in powoftwo() is -5 to +5 allowing a precision more fine than one cent in a range of ten octaves. If a greater range of values is required, use the slower opcodes ipow, kpow and apow.

logbtwo() returns the logarithm base two of x. The range of values admitted as argument is .25 to 4 (i.e. from -2 octave to +2 octave response). This function is the inverse of powoftwo().

These functions are fast, because they read values stored in tables.
Also they are very useful when working with tuning ratios. They work at i and k-rate.

Warning! values out of range will crash Csound with an invalid memory access error.

vlowres

ar vlowres asig, kfco, kres, iord, ksep;

DESCRIPTION

a bank of filters in which freqency cutoff can be separated under user control

INITIALIZATION

iord - total nuber of filter (1 to 10)

PERFORMANCE

ar - output signal
asig - input signal
kfco - frequency cutoff (not in cps)
ksep - frequency cutoff separation for each filter

vlowres (variable resonant lowpass filter) allow a variable response curve in resonant filters. It can be thought as a bank of lowpass resonant filters with the same resonance, serially connected. The frequency cutoff of each filter can vary with the kcutoff and ksep parameters.

flanger

ar flanger asig, adel, kfeedback, imaxd

DESCRIPTION

A user controlled flanger (see picture)

INITALIZATION

imaxd - maximum delay in seconds (needed for inital memory allocation)

PERFORMANCE

ar - output signal
asig - input signal
adel - delay in seconds
kfeedback - feedback amount (in normal tasks this should not exceed 1, even if bigger values are allowed)

This unit is useful for generating chourses and flangers. The delay must be varied at a-rate connecting adel to an oscillator output. Also the feedback can vary at k-rate.

This opcode is implemented to allow kr different than sr (else delay could not be lower than ksmps) enhancing realtime performance. (BtW: this unit is very similar to physic1, the only difference is flanger does not have the lowpass filter. See also the block diagram in figure 'flanger.bmp').

ntrpol

ir ntrpol isig1, isig2, ipoint [, imin, imax]
kr ntrpol ksig1, ksig2, kpoint [, imin, imax]
ar ntrpol asig1, asig2, kpoint [, imin, imax]

DESCRIPTION

Calculates the weighted mean value (i.e. linear interpolation) of two input signals

INITALIZATION

imin - minimum xpoint value (optional, default 0)
imax - maximum xpoint value (optional, default 1)

PERFORMANCE

xr - output signal
xsig1, xsig2 - input signals
xpoint - interpolation point beetween the two values

nterpol opcode outputs the linear interpolation beetween two input values. xpoint is the distance of evaluation point from the first value. With the default values of imin and imax, (0 and 1) a zero value indicates no distance from the first value and the maximum distance from the second one. With a 0.5 xntrpol value will output the mean value of the two inputs, indicating the exact half point beetween xsig1 and xsig2 . A 1 value indicates the maximum distance from the first value and no distance from the second one.

The range of xpoint can be also defined with imin and imax to make easier its management.
These opcodes are useful for crossfading two signals.

GEN23

This subroutine reads numeric values from an external ascii file

f# time size -23 "filename.txt"

The numeric values contained in "filename.txt" (which indicates the complete pathname of the ascii file to be read), can be separated by spaces, tabs, newline characters or commas.
Also words that contains non-numeric characters can be used as comments since they are ignored.
All characters following ';' (comment) are ignored until next line (numbers too).

GEN24

This subroutine reads numeric values from another allocated function-table and rescales them according to the max and min values given by the user.

f# time size -24 numsource min max

numsource must be an already allocated table with the same size of this function.
This GEN is useful, for example, to eliminate the starting offset in exponential segmets allowing a real starting from zero.

GEN40

This subroutine generates a continuous random distribution function starting from the shape of a user-defined distribution histogram.

f# time size -40 shapetab

The shape of histogram must be stored in a previously defined table, in fact shapetab argument must be filled with the number of such table. Histogram shape can be generated with any other GEN routines. Since no interpolation is used when GEN40 processes the translation, it is suggested that the size of the table containing the histogram shape to be reasonably big, in order to obtain more precision (however after the processing the shaping-table can be destroyed in order to re-gain memory). It is possible to generate tables having non-power-of-two length by giving a negative value to size argument.

This subroutine is designed to be used together with Cusrnd opcode (see Cusrnd for more information).

GEN41

This subroutine generates a discrete random distribution function by giving a list of numerical pairs.

f# time size -41 value1 prob1 value2 prob2 value3 prob3 ... valueN probN

The first number of each pair is a value, and the second is the probability of that value to be choosen by a random algorithm. Even if any number can be assigned to the probability element of each pair, it is suggested to give it a percent value, in order to make it clearer for the user. It is possible to generate a table having a non-power-of-two length by giving a negative value to size argument.

This subroutine is designed to be used together with Dusrnd and urd opcodes (see Dusrnd for more information).

GEN42

This subroutine generates a random distribution function of discrete ranges of values by giving a list of groups of three numbers.

f# time size -42 min1 max1 prob1 min2 max2 prob2 min3 max3 prob3 ... minN maxN probN

The first number of each group is a the minumum value of the first range, the second is the maximum value and the third is the probability of that an element belonging to that range of values to be choosen by a random algorithm. Even if any number can be assigned to the probability element of each group, it is suggested to give it a percent value, in order to make it clearer to the user. It is possible to generate a table having a non-power-of-two length by giving a negative value to size argument.

This subroutine is designed to be used together with Dusrnd and urd opcodes (see Dusrnd for more information). Since both Dusrnd and urd don't use any interpolation, it is suggested to give a size reasonably big.

foscili2

ar foscili2 xamp, kcps, kcar, kmod, kndx, ifn1, ifn2 [, iphs]

INITIALISATION

ifn1 - carrier function table number. Requires a wrap-around guard point.
ifn1 - modulator 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

This unit is very similar to 'foscili'. The only difference is in that the user can use two different function tables, the first for the carrier (ifn1) , the second for the modulator (ifn2).
See foscili help for more informations.

Midi Micro Tuning

cpstmid

icps cpstmid ifn

INITIALIZATION

ifn - function table containing the parameters (numgrades, interval, basefreq, basekeymidi) and the tuning ratios.

(init rate only)

This unit is similar to cpsmidi, but allows fully customized micro-tuning scales. It requires five parameters, the first ifn is the function table number of the tuning ratios, and the other parameters must be stored in the function tables itself.
The function table ifn should be generated by the GEN2 and the first four values stored in this function are:

numgrades (the number of grades of the micro-tuning scale),
interval (the frequency range covered before repeating the grade ratios, for example 2 for one octave, 1.5 for a fift etcetera), basefreq (the base frequency of the scale in cps),
basekeymidi (the midi-note-number to which to assign the basefreq unmodified).

After these four values, the user can begin to insert the tuning ratios. For example, for a standard 12-grade scale with the base-frequency of 261 cps assigned to the key-number 60, the corresponding f-statement in the score to generate the table should be:

;           numgrades    basefreq     tuning-ratios (eq.temp) .......

;                  interval    basekeymidi

f1 0 64 -2  12     2     261   60     1   1.059463 1.12246 1.18920 ..etc...

Another example with a 24-grade scale with a base frequency of 440 assigned to the key-number 48, and a repetition interval of 1.5:

;                  numgrades       basefreq      tuning-ratios .......

;                          interval       basekeymidi

f1 0 64 -2         24      1.5     440    48     1   1.01  1.02  1.03   ..etc...

call,calld,callm,callmd

call instrno, iactime, idur [,ip4,ip5,ip6,ip7,... ,ipn ]
calld instrno, iactime, idur [,ip4,ip5,ip6,ip7,... ,ipn ]
callm instrno, iactime [,ip3,ip4,ip5,ip6,ip7,... ,ipn ]
callmd instrno, iactime, idur [,ip4,ip5,ip6,ip7,... ,ipn ]

DESCRIPTION

Activate an instrument from within another instrument at performance time (subroutine call)

INITIALIZATION

instrno - instrument number to be activated
iactime - action time in seconds (should be zero when using call)
idur - duration of the note to be activated
ip3,ip4,ip5,ip6, ... ,ipn - p-fields of the instrument to be activated

PERFORMANCE

An instrument containing call (instrument call), calld (delayed instrument call), callm (MIDI-oriented instrument call) or callmd (delayed MIDI-oriented instrument call) opcodes, can activate an instance of another instrument of the same orchestra during the performance.

These opcodes can also be thinked as subroutine calls. Any number of additional init arguments (ip4,ip5,ip6 etc.) can be sent to the target instruments, in the same way of p-fields in a score note event.

More instances of call, calld, callm and callmd can co-exist in the same calling instr, so chords of more notes (played by different target instruments) can be activated by a single MIDI note-on event, as well as by a single i-statement in the score. This possibility allows the user to do several things, for example to easily implement multi-layered instruments, or tho inherit the features of an instrument by a more specialized instrument (by using this opcodes together with the parmXX and rtrnXX opcode family, see below).

A multiple inheritance of several instruments can be also implemented by using these opcodes in Csound.

The difference beetween the four opcodes concerns the activation and the duration of the target note, and is described below:

call plays the target note immediately (so 'iactime' argument must be set to zero), and its duration is 'idur' seconds, even if the caller instrument is turned off beforehand or afterward. This opcode has no output and operates at i-rate only.
calld can schedule the target note activation 'iactime' seconds after the caller instrument init-time. Again, the target note duration is 'idur' seconds, even if the caller instrument is turned off beforehand or afterward. This opcode has no output and operates at k-rate.
callm plays the target note immediately (so iactime argument must be set to zero), but its duration is indeterminate and depends by a midi midi note-off message recognized by the caller instrument. This opcode is useful when the caller instrument is activated by MIDI. In fact in this case it is impossible to know the caller duration beforehand. Notice that it is still possible to use call and calld with a MIDI-activated caller instrument instead of callm. In that case the target notes will be simply turned off after idur seconds, whether the caller instr is turned off before or after idur seconds are elapsed or it isn't. callm has no output and operates at k-rate.
callmd can schedule the target note activation iactime seconds after the caller instrument init-time. The duration of the target note is indeterminate (so 'idur' parameter is meaningless) and depends by a midi note-off message recognized by the caller instrument. The target note is not allocated until iactime seconds are elapsed. callmd has no output and operates at k-rate.

Notice that each of these opcodes makes the processing point do not return to the caller until all the target instr initialization phase has been completed.

;//////////////////////////////////////

;//////////      EXAMPLE 1    /////////

;//////////  call and calld   /////////

;//////////////////////////////////////

gifn    ftgen 1,0,1024,10,1,0,0,0,0,0,0,.5,0,0,0,0,0.2

;***************************************************

        instr   1       ;**** caller instrument ****

;***************************************************

ifreq   cpsmidi

        call   2,0,2, 2000,ifreq

        calld 2,1,4, 2000,ifreq*1.2

        calld 2,3,6, 2000,ifreq*1.77

        calld 2,5,8, 2000,ifreq*2.1

        calld 2,8,10,2000,ifreq*2.4555

        endin

;***************************************************

    instr   2       ;**** target instrument ****

;***************************************************

k1      linseg  0,p3/2,1,p3/2,0

a1       oscili  p4,p5,gifn

      out     a1*k1

   endin

;//////////////////////////////////////

;//////////     EXAMPLE 2      ////////

;////////// callm and callmd ////////

;//////////////////////////////////////

gifn    ftgen 1,0,1024,10,1,0,0,0,0,0,0,.5,0,0,0,0,0.2

;***************************************************

        instr   1       ;**** caller instrument ****

;***************************************************

iamp    ampmidi 2000

ifreq   cpsmidi

        callm  2,0,2 ,iamp,      ifreq

        callmd 2,1,4 ,iamp * .5, ifreq * 1.2

        callmd 2,3,6 ,iamp * .25,ifreq * 1.77

        callmd 2,6,8 ,iamp * .2, ifreq * 2.1

        callmd 2,8,10,iamp * .1, ifreq * 2.4555

        endin

;***************************************************

        instr   2       ;**** target instrument ****

;***************************************************

k1      linenr  1,p3/2,p3/2,.03

a1      oscili  p4,p5,gifn

        out     a1*k1

        endin

parmck, parmtk, parmca, parmta, rtrnck, rtrntk, rtrnca, rtrnta parmck kinarg1, kinarg2, kinarg3,....kinargN parmtk koutarg1,koutarg2,koutarg3,...koutargN parmca ainarg1, ainarg2, ainarg3,....ainargN parmta aoutarg1,aoutarg2,aoutarg3,...aoutargN rtrnck koutarg1,koutarg2,koutarg3,...koutargN rtrntk kinarg1, kinarg2, kinarg3,....kinargN rtrnca aoutarg1,aoutarg2,aoutarg3,...aoutargN rtrnta ainarg1, ainarg2, ainarg3,....ainargN DESCRIPTION These opcodes deal with a-rate and k-rate argument-signals and return signals to be sent when using subroutine calls PERFORMANCE kinarg1, kinarg2, kinarg3,....kinargN - k-rate input arguments koutarg1,koutarg2,koutarg3,...koutargN - k-rate output arguments ainarg1, ainarg2, ainarg3,....ainargN - a-rate input arguments aoutarg1,aoutarg2,aoutarg3,...aoutargN - a-rate output arguments This opcode family allows the user to define input and output signals to use as arguments (or parameters) and return values when calling a subroutine (together with the call opcode family). Some k-rate examples will be presented below, the corresponding a-rate oriented opcodes can be used in the same way, the only difference is that the arguments are a-rate variables. parmck (k-rate parameters handling to be placed in the caller instrument) and parmtk (k-rate parameters handling to be placed in the target instrument) work in pair. The caller instrument can send several k-rate signals to the target instrument by using this couple of opcodes: ;*************************************************** instr 1 ;**** caller instrument **** ;*************************************************** ;**** calculating the k-rate arguments to be sent to the target instrument karg1 oscil ... karg2 linen ... karg3 expseg ... karg4 linseg ... ;**** instrno actime dur init-rate arguments sent to instr 2 call 2, 0, 3, iarg1,iarg2,iarg3 ;*** call the target instr parmck karg1,karg2,karg3,karg4 ;*** send the four signals ..... endin ;*************************************************** instr 2 ;**** target instrument **** ;*************************************************** ..... parmtk k1,k2,k3,k4 ;*** receive the four signals from the caller instr &n bsp; ;*** using the k-rate arguments... a1 oscil k1,k2,k3,1 out a1*k4 ..... endin In this case instr 1 (the caller) calls instr 2 (the target) and sends three i-rate variables (iarg1, iarg2 and iarg3 which are interpreted as p4, p5 and p6 by the target instr) and four k-rate arguments (karg1,karg2,karg3,karg4 which are interpreted by the target instrument as k1,k2,k3 and k4 local variables) to the target instrument. IMPORTANT: Notice that, in the previous example, the k1,k2,k3 and k4 arguments of parmtk opcode are output arguments, even if they appear on the right of the opcode instead of on the left. This because Csound at the moment doesn't support a variable number of arguments at the left of the opcode. Also you must put parmck (as well as parmca) immediately after the call opcode. rtrnck (k-rate return values received by the caller instrument) and rtrntk (k-rate return values sent by the target instrument) work in pair. The target instrument can return several k-rate signals to the caller intrument by using these two pcodes. The following example shows this concept: ;*************************************************** instr 1 ;**** caller instrument **** ;*************************************************** ;**** calculating the k-rate arguments.... ;**** to be sent to the target instrument .... ;**** instrno actime dur init-rate arguments sent to instr 2 call 2, 0, 3, iarg1,iarg2,iarg3 ;*** call the target instr rtrnck karg1,karg2,karg3,karg4 ;*** receive the return signals from the target instr ;*** using the return signals ... a1 oscil karg1,karg1,karg1,1 out a1*karg1 ..... endin ;*************************************************** instr 2 ;**** target instrument **** ;*************************************************** ..... ;*** generating k-rate signals to be returned to the caller instr... k1 oscil ... k2 linseg ...k3 oscil1 ... k4 expseg .... rtrntk k1,k2,k3,k4 ;*** return the four signals to the caller instr ..... endin It is important to be sure that the number of arguments of the pair parmck/parmtk and rtrnck/rtrntk is the same. Using a-rate opcodes (parmca/parmta and rtrnca/rtrnta) is almost identical. Here is a summing-up example: ;**** ;**** An example of parmck, parmca, parmtk, parmta, rtrnck,rtrnca, rtrntk and rtrnta opcodes ;**** sr = 44100 kr = 441 ksmps = 100 nchnls = 2 gifn ftgen 1,0,1024,10 ,1 ,0,0,0,0,0,0,.1,0,0,0,0,0,.05,0,0,0,0,0,0,0,.01 gikfn ftgen 2,0,1024,10 ,1 ;*************************************************** instr 1 ;**** caller instrument **** ;*************************************************** iamp ampmidi 2000 ifreq cpsmidi a1 oscili iamp, ifreq, gifn a2 oscili iamp, ifreq*1.3, gifn a3 oscili iamp, ifreq*1.5555, gifn k1 oscili 1, .5, gikfn k2 oscili 1, 1.3, gikfn k3 oscili 1, 2.1.5555, gikfn xtratim 2 ;when using a-rate arguments in subroutine call, ;you must be sure that the extra-time of the instrument ; ;containing the out opcode is ;grater or equal to that of the target instr ;//////// first call ///////////// callm 2,0,4,iamp, ifreq ;call instr 2 as subroutine parmck k1,k2,k3 ;send k-rate arguments to instr 2 parmca a1,a2,a3 ;send a-rate arguments to instr 2 rtrnca aout1,aout2 ;receive a-signals returned by the first call of instr 2 ;//////// second call ///////////// callm 2,0,4,iamp, ifreq*2.2 ;call instr 2 as subroutine parmck k3,k2,k1 ;send k-rate arguments to instr 2 parmca a3,a1,a2 ;send a-rate arguments to instr 2 rtrnck kenv ;receive k-signals returned by the second call of instr 2 rtrnca aout3,aout4 ;receive a-signals returned by the second call of instr 2 &nbs p; outs (aout1+aout3)*kenv, (aout2+aout4)*kenv endin ;*************************************************** instr 2 ;**** target instrument **** ;*************************************************** parmtk ksig,ksig2,ksig3 ;receive k-signals sent by caller arguments parmta asig,asig2,asig3 ;receive a-signals sent by caller arguments k1 linenr 1,p3/2,p3/2,.03 a1 oscili p4*ksig,p5,gifn a2 oscili p4*ksig2,p5*1.5,gifn a3 oscili p4*ksig3,p5*1.8,gifn rtrntk k1 ;return k-signals rtrnta a1+asig2+asig3, a2+a3+asig ;return a-signals endin fout, foutk, fouti, foutir, fiopen fout "ifilename", iformat, aout1 [, aout2, aout3,.... ,aoutN] foutk "ifilename", iformat, kout1 [, kout2, kout3,....,koutN] fouti ihandle, iformat, iflag, iout1 [, iout2, iout3,....,ioutN] foutir ihandle, iformat, iflag, iout1 [, iout2, iout3,....,ioutN] ihandle fiopen "ifilename",imode DESCRIPTION fout, foutk, fouti and foutir output N audio, k or i-rate signals to a specified file of N channels. fiopen can be used to open a file in one of the specified modes. INITIALIZATION ifilename - a double-quote delimited string file name iformat - a flag to choose output file format: for fout and foutk only: 0 - 32-bit floating point samples without header (binary PCM multichannel file) 1 - 16-bit integers without header (binary PCM multichannel file) 2 - 16-bit integers with .wav type header (Microsoft WAV mono or stereo file) for fouti and foutir only: 0 - floating point in text format 1 - 32-bit floating point in binary format iflag - choose the mode of writing to the ascii file (valid only in ascii mode; in binary mode iflag has no meaning, but it must be present anyway). iflag can be a value choosen among the following: 0 - line of text without instrument prefix 1 - line of text with instrument prefix (see below) 2 - reset the time of instrument prefixes to zero (to be used only in some particular cases. See below) iout,... ioutN - values to be written to the file. imode - choose the mode of opening the file. imode can be a value choosen among the following: 0 - open a text file for writing 1 - open a text file for reading 2 - open a binary file for writing 3 - open a binary file for reading PERFORMANCE aout1,... aoutN - signals to be written to the file. kout1,...koutN - signals to be written to the file. fout (file output) writes samples of audio signals to a file with any number of channels. Channel number depends by the number of aoutN variables (i.e. a mono signal with only an a-rate argument, a stereo signal with two a-rate arguments etc.) Maximum number of channels is fixed to 64. More fout opcodes can be present in the same instrument, referring to different files. Notice that, differently by out, outs and outq, fout does not zeroes the audio variable, so you must provide a zeroing after calling fout if poliphony is used. You can use incr and clear opcodes for this task. foutk operates in the same way of fout, but with k-rate signals. iformat can be set only to 0 or 1. fouti and foutir write i-rate values to a file. The main use of these opcodes is to generate a score file during a realtime session. For this purpose the user should set iformat to 0 (text file output) and iflag to 1, which enable the output of a prefix consisting of the following strings: i num actiontime duration before the values of iout1...ioutN arguments. Prefix is referring to instrument number, action time and duration of current note. The difference of fouti and foutir is that, in the case of fouti, when iflag is set to 1, the duration of the first opcode is undefined (so it is replaced by a dot ) wheras in the case of foutir is defined at the end of note, so the corresponding text line is written only at the end of the current note (in order to recognize its duration). The corresponding file is linked by the ihandle value generated by fiopen opcode (see below). So fouti and foutir can be used to generate a Csound score while playing a realtime session. fiopen opens a file to be used by the foutX opcodes. It must be defined externally by any instruments, in the header section. It returns a number ihandle, which is univocally referring to the opened file. Notice that fout and foutk can use both a string containing a file pathname or a handle-number generated by fiopen, wheras in the case of fouti and foutir, the target file can be only specified by means of a handle-number. fin, fink, fini fin "ifilename", iskipframes, iformat, ain1 [, ain2, ain3,.... ,ainN] fink "ifilename", iskipframes, iformat, kin1 [, kin2, kin3,.... ,kinN] fini "ifilename", iskipframes, iformat, in1 [, in2, in3,.... ,inN] DESCRIPTION read signals from a file (at a, k, and i-rate) INITIALIZATION ifilename - input file name (can be a string or a handle number generated by fiopen) iskipframes - number of frames to skip at the start (every frame contains a sample of each channel) iformat - a number specifying the input file format: for fin and fink: 0 - 32 bit floating points without header 1 - 16 bit integers without header for fini: 0 - floating points in text format (loop; see below) 1 - floating points in text format (no loop; see below) 2 - 32 bit floating points in binary format (no loop) fin (file input) is the complement of fout: it reads a multi channel file to generate audio rate signals. At present time no header is supported for file format. The user must be sure that the number of channel of the input file is the same of the number of ainX arguments fink is the same as fin, but operates at k-rate. fini is the complement of fouti and foutir, it reads the values each time the corresponding instrument note is activated. When iformat is set to 0, if the end of file is reached the file pointer is zeroed, restarting the scanning from the beginning. When iformat is set to 1 or 2 no loop is enabled, so at the end of file the corresponding variables will be filled with zeroes. vincr, clear vincr asig, aincr clear avar1 [,avar2, avar3,...,avarN] DESCRIPTION vincr increments an audio variable of another signal, i.e. accumulates output. clear zeroes a list of audio signals. PERFORMANCE asig - audio variable to be incremented aincr - incrementation signal avar1 [,avar2, avar3,...,avarN] - signals to be zeroed vincr (variable increment) and clear are thinked to be used togheter. vincr stores the result of the sum of two audio variables into the first variable itself (which is thinked to be used as accumulator in case of polyphony). The accumulator-variable can be used for output signal by means of fout opcode. After the disk writing operation, the accumulator-variable should be set to zero by means of clear opcode (or it will explode). fold ar fold asig, kincr DESCRIPTION Adds artificial foldover to an audio signal PERFORMANCE asig - input signal kincr - amount of foldover expressed in multiple of sampling rate. Must be >= 1 fold is an opcode which creates artificial foldover. For example, when kincr is equal to 1 with sr=44100, no foldover is added, when kincr is set to 2 the foldover is equivalent to a downsampling to 22050, when it is set to 4 to 11025 etc. Fractional values of kincr are possible, allowing a continuous variation of foldover amount. This can be used for a wide range of special effects. EXAMPLE: instr 1 kfreq line 1,p3,200 a1 oscili 10000, 100, 1 k1 init 8.5 a1 fold a1, kfreq out a1 endin resony ar resony asig, kbf, kbw, inum, ksep [, iscl, istor] DESCRIPTION A bank of second-order bandpass filters, connected in parallel. INITIALIZATION inum - number of filters. 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. istor - initial disposition of internal data space. Since filtering incorporates a feedback loop of previous output, the initial status of the storage space used is significant. A zero value will clear the space; a non-zero value will allow previous information to remain. The default value is 0. PERFORMANCE asig - audio input signal kbf - base frequency, i.e. center frequency of lowest filter in Hz kbw - bandwidth in Hz ksep - separation of the center frequency of filters in octaves resony is a bank of second-order bandpass filters, with k-rate variant frequency separation, base frequency and bandwidth, connected in parallel (i.e. the resulting signal is a mixing of the output of each filter). The center frequency of each filter depends of kbf and ksep variables. The maximum number of filters is set to 100. EXAMPLE: asig, kbf, kbw, inum, ksep [, iscl, istor] In this example the global variable gk1 modifies kbf, gk2 modifies kbw, gk3 inum, gk4 ksep and gk5 the main volume. instr 1 a1 soundin "myfile.aif" a2 resony a1, gk1 , gk2 ,i(gk3),gk4 ,2 out a2 * gk5 endin cpuprc cpuprc instrnum, ipercent DESCRIPTION Set the cpu processing-time percent usage of an instrument in order to avoid buffer underrun in realtime performances. INITIALIZATION instrnum - instrument number ipercent - percent of cpu processing-time to assign cpuprc is an opcode that enables a sort of polyphony theshold. The user must set ipercent value for each instrument he want to activate in realtime. Assumnig that the total theorical processing time of the cpu of the computer is 100%, this percent value can only be defined empirically, because there are too many factors that contribute to limit realtime polyphony in different computers. For example if ipercent is set to 5% for instrument 1, the maximum number of voices that can be allocated in realtime, can be 20 (as 5% X 20 = 100%). If the user attempts to play a further note while the 20 previous notes are still playing, Csound inhibits the allocation of that note and will display the following warning message: can't allocate last note because it exceeds 100% of cpu time ipercent can be expressed also as a fractional value. In order to avoid audio buffer underruns, it is suggested to set the maximum number of voices a bit below the real processing power of the computer, because sometimes an instrument can require more processing time than normal (for example, if the instrument contains an oscillator which reads a table that doesn't fit in cache memory, it will be slower than normal; also, any concurrent program which run in multitasking, can subtract more processing power in some cases, less power in other cases etc.) At start, all instruments are set to a default value of ipercent = 0.0% (i.e. zero processing time or rather infinite cpu processing-speed). This setting is OK for deferred-time sessions. All instances of cpuprc must be defined in the header section, not in the instrument body. example: sr=44100 kr=441 ksmps=100 nchnls=2 cpuprc 1, 2.5 ;** set instr 1 to 2.5% of processor power, i.e. maximum 40 voices (2.5% X 40 = 100%) cpuprc 2, 33.333 ;** set instr 2 to 33.333% of processor power, i.e. maximum 3 voices (33.333% X 3 = 100%) instr 1 ...body... endin instr 2 ....body... endin tab, tabw ir tab_i indx, ifn[, ixmode] kr tab kndx, ifn[, ixmode] ar tab xndx, ifn[, ixmode] tabw_i isig, indx, ifn [,ixmode] tabw ksig, kndx, ifn [,ixmode] tabw asig, andx, ifn [,ixmode] DESCRIPTION Fast table opcodes. Faster than table and tablew because don't allow wrap-around and limit and don't check index validity. Have been implemented in order to provide fast access to arrays. Support non-power of two tables (can be generated by any GEN function by giving a negative length value). INITIALIZATION ifn - table number ixmode (optional; default = 0) - ==0 - xndx and ixoff ranges match the length of the table. !=0 - xndx and ixoff have a 0 to 1 range. isig - input value to write indx - table index PERFORMANCE asig, ksig - input signal to write andx, kndx - table index tab and tabw opcodes are similar to table and tablew, but are faster and support tables having non-power-of-two length. Special care of index value must be taken into account. Index values out of the table allocated space will crash Csound. random, randomi, radomh ir random imin, imax kr random kmin, kmax ar random kmin,kmax kout randomi kmin, kmax, kcps aout randomi kmin, kmax, acps kout randomh kmin, kmax, kcps aout randomh kmin, kmax, acps DESCRIPTION Output is a controlled pseudo-random number series between min and max INITIALIZATION imin - minimum range limit imax - maximum range limit PERFORMANCE kmin - minimum range limit kmax - maximum range limit kcps, acps - rate of random break-point generation random opcode is similar to linrand and trirand but allows the user to set arbitrary minimum and maximum values. randomi is similar to randi but allows the user to set arbitrary minimum and maximum values. randomh is similar to randh but allows the user to set arbitrary minimum and maximum values. The Xcps parameters of randomh and randomi permit the user to specify that new random numbers are to be generated at a rate less than the sampling or control frequencies. randomh will hold each new number for the period of the specified cycle; randomi will produce straightline interpolation between each new number and the next. See also randi and randh. All these opcodes use a custom, high-speed 31-bit random number generator. For all these opcodes, use seed opcode to give a new random-generation seed. duserrnd, cuserrnd iout duserrnd itableNum kout duserrnd ktableNum aout duserrnd atableNum iout = urd(itableNum) kout = urd(ktableNum) aout = urd(atableNum) iout cuserrnd imin, imax, itableNum kout cuserrnd kmin, kmax, ktableNum aout cuserrnd amin, amax, atableNum DESCRIPTION Output is a controlled pseudo-random number series. In these cases, the random distributions are created by the user. INITIALIZATION itableNum - number of table containing the random-distribution function. Such table is generated by the user. See GEN40, GEN41 and GEN42. The table length doesn't need to be a power of 2 imin - minimum range limit imax - maximum range limit PERFORMANCE ktableNum - number of table containing the random-distribution function. Such table is generated by the user. See GEN40, GEN41 and GEN42. The table length doesn't need to be a power of 2 kmin - minimum range limit kmax - maximum range limit duserrnd (discrete user-defined-distribution random generator) generates random values according to a discrete random distribution created by the user. The user can create the discrete distribution histogram by using GEN41. In order to create that table, the user has to define an arbitrary amount of number pairs, the first number of each pair representing a value and the second representing its probability (see GEN41 for more details). urd is the same opcode as duserrnd, but can be used in function fashion. When used as a function, the rate of generation depends by the rate type of input variable XtableNum. In this case it can be embedded into any formula. Table number can be varied at k-rate, allowing to change the distribution histogram during the performance of a single note. duserrnd is designed be used in algorithmic music generation. duserrnd can also be used to generate values following a set of ranges of probabilities by using distribution functions generated by GEN42 (See GEN 42 for more details). In this case, in order to simulate continuous ranges, the length of table XtableNum should be reasonably big, as duserrnd doesn't interpolate beetween table elements. cuserrnd (continuous user-defined-distribution random generator) generates random values according to a continuous random distribution created by the user. In this case the shape of the distribution histogram can be drawn or generated by any GEN routine. The table containing the shape of such histogram must then be translated to a distribution function by means of GEN40 (see GEN40 for more details). Then such function must be assigned to the XtableNum argument of cuserrnd. The output range can then be rescaled according to the Xmin and Xmax arguments. cuserrnd linearly interpolates beetween table elements, so it is not recommended for discrete distributions (GEN41 and GEN42). For a tutorial about random distribution histograms and functions see: D. Lorrain. "A panoply of stochastic cannons". In C. Roads, ed. 1989. Music machine. Cambridge, Massachusetts: MIT press, pp. 351 - 379. vibrato, vibr, jitter, jitter2 kout vibrato kAverageAmp, kAverageFreq, kRandAmountAmp, kRandAmountFreq, kAmpMinRate, kAmpMaxRate, kcpsMinRate, kcpsMaxRate, ifn [, iphs] kout vibr kAverageAmp, kAverageFreq, ifn kout jitter kamp, kcpsMin, kcpsMax kout jitter2 ktotamp, kamp1, kcps1, kamp2, kcps2, kamp3, kcps3 DESCRIPTION These opcode are designed to make sounds more natural to hearing. vibrato and vibr generates a vibrato-like signal containing some user-controlled randomness in amplitude and frequency; jitter and jitter2 produces some deviation to be summed to constant signals to make them more "analog-like" and natural. INITIALIZATION ifn - number of vibrato table. It normally contains a sine or a triangle wave. iphs (optional) - initial phase of table, expressed as a fraction of a cycle (0 to 1). A negative value will cause phase initialization to be skipped. The default value is 0. PERFORMANCE kAverageAmp - average amplitude value of vibrato kAverageFreq - average frequency value of vibrato (in cps) kRandAmountAmp - amount of random amplitude deviation kRandAmountFreq - amount of random frequency deviation kAmpMinRate - minimum frequency of random amplitude deviation segments (in cps) kAmpMaxRate - maximum frequency of random amplitude deviation segments (in cps) kcpsMinRate - minimum frequency of random frequency deviation segments (in cps) kcpsMaxRate - maximum frequency of random frequency deviation segments (in cps) kamp - amplitude of jitter deviation kcpsMin - minimum speed of random frequency variations (expressed in cps) kcpsMax - maximum speed of random frequency variations (expressed in cps) ktotamp - resulting amplitude of jitter2 kamp1 - amplitude of the first jitter component kcps1 - speed of random variation of the first jitter component (expressed in cps) kamp2 - amplitude of the second jitter component kcps2 - speed of random variation of the second jitter component (expressed in cps) kamp3 - amplitude of the third jitter component kcps3 - speed of random variation of the third jitter component (expressed in cps) vibrato outputs a natural-sounding user-controllable vibrato. The concept is to randomly vary both frequency and amplitude of the oscillator generating the vibrato, in order to simulate the irregularities of a real vibrato. In order to have a total control of these random variations, several input arguments are present. Random variations are obtained by two separated segmented lines, the first controlling amplitude deviations, the second the frequency deviations. Average duration of each segment of each line can be shortened or enlarged by the arguments kAmpMinRate, kAmpMaxRate, kcpsMinRate, kcpsMaxRate, and the deviation from the average amplitude and frequency values can be independently adjusted by means of kRandAmountAmp and kRandAmountFreq. vibr is an easier-to-use version of vibrato. It has the same generation-engine of vibrato, but the parameters corresponding to missing input arguments are hard-coded to default values. jitter generates a segmented line whose segments are randomly generated inside the +kamp and -kamp interval. Duration of each segment is a random value generated according to kcpsmin and kcpsmax values. jitter2 also generates a segmented line such as jitter, but in this case the result is similar to the sum of three randi opcodes, each one with a different amplitude and frequency value (see randi for more details), that can be varied at k-rate. Different effects can be obtained by varying the input arguments. jitter and jitter2 can be used to make more natural and "analog-sounding" some static, dull sound. For best results, It is suggested to keep their amplitude moderate. SoundFont2-related opcodes ifilhandle sfload "filename" sfplist ifilhandle sfilist ifilhandle sfpassign istartindex, ifilhandle ipreindex sfpreset iprog, ibank, ifilhandle, ipreindex a1, a2 sfplay ivel, inotnum, xamp, xfreq, ipreindex [, iflag, ioffset] a1 sfplaym ivel, inotnum, xamp, xfreq, ipreindex [, iflag, ioffset] a1, a2 sfinstr ivel, inotnum, xamp, xfreq, instrNum, ifilhandle [, iflag, ioffset] a1 sfinstrm ivel, inotnum, xamp, xfreq, instrNum, ifilhandle [, iflag, ioffset] a1, a2 sfplay3 ivel, inotnum, xamp, xfreq, ipreindex [, iflag, ioffset] a1 sfplay3m ivel, inotnum, xamp, xfreq, ipreindex [, iflag, ioffset] a1, a2 sfinstr3 ivel, inotnum, xamp, xfreq, instrNum, ifilhandle [, iflag, ioffset] a1 sfinstr3m ivel, inotnum, xamp, xfreq, instrNum, ifilhandle [, iflag, ioffset] DESCRIPTION Csound now supports SoundFont2 format. These opcodes allow to manage the sample-structure of SoundFont2 files. INITIALIZATION filename - name of the SoundFont2 file (complete pathname). You must use "/" to separate directories even under Windows. It must be typed within double-quotes. ifilhandle - unique number generated by sfload opcode to be used as an identifier of a SoundFont2 file, since several SoundFont2 files can be loaded and activated at the same time. istartindex - starting preset index set by the user in bulk preset assignments (see below). ipreindex - preset index iprog - program number of a bank of presets of a SoundFont2 file ibank - number of a specific bank of a SoundFont2 file ivel - velocity value inotnum - note number value iflag - flag regarding the behaviour of xfreq (see below). ioffset - playing starting offset, in samples instrNum - number of an instrument of a SoundFont2 file. PERFORMANCE xamp - amplitude correction factor xfreq - frequency value or frequency correction factor (depending by iflag, see below) SoundFont2 is a widespread standard which allow to embed banks of wavetable-based sounds into a binary file. In order to understand the usage of these opcodes, the user must know some notion about SF2 format. So a brief description of this format follows. The SoundFont2 format is made by generator and modulator objects. All current Csound opcodes regarding SF2 support generator section only, so we will only deal with the generator-related structure of SF2 format, omitting the modulators. There are several levels of generators having a hierarchical structure. The most basic kind of generator object is a sample. Samples can or can't be be looped and are associated to a MIDI note number, called base-key. When a sample is associated with a range of MIDI note numbers, with a range of velocities, with a transposition (coarse and fine tuning), with a scale tuning, and with a level scaling factor, such sample makes up a split. A set of splits, together with a name, makes up an instrument. When an instrument is associated with a key range, with a velocity range, with a level scaling factor, and with a transposition, it makes up a layer. A set of layers, together with a name, makes up a preset. Presets are normally the final sound-generating structures ready for the user. They generate sound according to the settings of their lower-level components. Here is a picture of that structure: Both sample data and structure data is embedded in the same SoundFont2 binary file. A single SF2 file can contain up to a maximum of 128 banks of 128 preset programs, for a total of 16384 presets each one. Maximum number of layers, instruments, splits and samples is not defined, and probably is only limited by the computer memory. sfload opcode loads an entire SF2 file in memory. It returns a file handle to be used by other opcodes. Several instances of sfload can placed in the header section of an orchestra, allowing to work with more-than-one SF2 files at the same time. sfplist prints a list of all presets of a previously loaded SF2 file to the console. sfilist prints a list of all instruments of a previously loaded SF2 file to the console. sfpassign assigns all presets of a previously loaded SF2 file to a sequence of progressive index numbers, to be used later with the opcodes sfplay and sfplaym. The user can enstabilish the first index number by setting startindex argument. Any number of sfpassign instances can be placed in the header section of an orchestra, each one assigning presets belonging to different SF2 files. The user must take care that preset index numbers of different SF2 files don't cross themselves. sfpreset assigns an existing preset of a previously-loaded SF2 file to an index number, to be used later with the opcodes sfplay and sfplaym. The user must previously know the program and the bank numbers of the preset in order to fill the corresponding arguments. Any number of sfpreset instances can be placed in the header section of an orchestra, each one assigning a different preset belonging to the same (or different) SF2 file to different index numbers. sfplay plays a preset generating a stereo sound. ivel argument doesn't directly affect output amplitude, but informs sfplay opcode about what sample has to be choosen in multi-sample velocity-splitted presets. inotnum argument sets the frequency of the output when iflag = 0. When iflag == 1, inotnum doesn't directly affect the frequency of the output (see below). Adjustment of amplitude can be done by varying the xamp argument, that actually is a multiplier factor. The behaviour of xfreq depends from the value of iflag argument: 1. when iflag = 0 (or missing as this value is the default) xfreq argument is a multiplier of a the default frequency assigned by SF2 preset to the inotenum value. This can correct the default frequency (for example to obtain vibrato or some other frequency -shift effect). 2. when iflag = 1 xfreq argument should contain the actual frequency of the output sound in cps. This allow the user to use any kind of micro-tuning based scales. However this flag is designed to work correctly only with presets tuned to the default equal temerament. Don't try to use this flag value with preset already having non-standard tunings or with drum-kit-based presets, since unespected results could occurr. Notice that both xamp and xfreq arguments can contain k-rate signals as well as a-rate signals, but the user must be sure that both arguments are filled with variables of the same rate, or sfplay will not work correctly. ioffset argument allows to start the sound from a sample different from the first one. User should be sure that its value is within the length of the specific sound played in that moment, otherwise Csound will probably crash. The user must be sure that ipreindex argument is filled with a number containing a previously assigned preset, otherwise Csound will crash. sfplaym opcode is a mono version of sfplay. It should be used with mono preset, or with the stereo presets in wich stereo output is not required, because is a bit faster than sfplay. sfinstr plays an SF2 instrument instead of a preset (an SF2 instrument is the base of a preset layer). instrnum argument contains the instrument number, and the user must be sure that such number belongs to an existent instrument of a determinate soundfont bank. Notice that both xamp and xfreq arguments can contain k-rate signals as well as a-rate signals, but, also in this case, the user must be sure that both arguments are filled with variables of the same rate, or sfinstr will not work correctly. sfinstrm plays is a mono version of sfinstr. This is the fastest opcode of the SF2 family. sfplay3, sfplay3m, sfinstr, sfinstr3m are cubic-interpolation versions of previous opcodes. Difference of sound-quality is noticeable specially in bass-frequency-transposed samples. In high-freq-transposed samples the difference is less noticeable, and I suggest to use linear-interpolation versions, because they are faster. These Csound opcodes only handle sampling structure of SF2 files, because support of modulator objects (amplitude envelopes, frequency modulation, filter envelopes and modulation) is very basic and trivial in SF2 standard; so, adding any kind of modulation or processing to the sample data is completely left to the Csound user, bypassing all restrictions forced by the SF2 standard. Sequence-related opcodes ktrig seqtime ktime_unit, kstart, kloop, initndx, kfn_times ktrig seqtime2 ktrig_in, ktime_unit, kstart, kloop, kinitndx, kfn_times trigseq ktrig_in, kstart, kloop, initndx, kfn_values, kout1 [, kout2, kout3, ...., koutN] DESCRIPTION Handle timed-sequences of groups of values stored into tables. INITIALIZATION initndx - initial index PERFORMANCE kinitndx - reinit starting index ktrig - output trigger signal. Normally a stream of zeros, except when a new time value stored in the table is reached. In this case the ktrig argument is filled with the time value, scaled according to current ktime_unit value. ktime_unit - unit of measure of time, related to seconds. kstart - start index of looped section kloop - end index of looped section kfn_times - number of table containing a sequence of times kfn_values - numer of a table containing a sequence of groups of values ktrig_in - input tirgger signal kout1 [, kout2, kout3, ...., koutN] - output values These opcodes handle timed-sequences of groups of values stored into tables. seqtime generates a trigger signal (a sequence of impulses, see also trigger opcode), according to the values stored in kfn_times table. This table should contain a series of delta-times (i.e. times beetween to adiacent events). The time units stored into table are expressed in seconds, but can be rescaled by means of ktime_unit argument. The table can be filled with GEN02 or by means of an external text-file containing numbers, with GEN23. It is possible to start the sequence from a value different than the first, by assigning to initndx an index different than zero (which corresponds to the first value of the table). Normally the sequence is looped, and the start and end of loop can be adjusted by modifying kstart and kloop arguments. User must be sure that values of these arguments (as well as initndx) correspond to valid table numbers, otherwise Csound will crash (because no range-checking is implementeted). It is possible to disable loop (one-shot mode) by assigning the same value both to kstart and kloop arguments. In this case, the last read element will be the one corresponding to the value of such arguments. Table can be read backward by assigning a negative kloop value. It is possible to trigger two events almost at the same time (actually separated by a k-cycle) by giving a zero value to the corresponding delta-time. First element contained in the table should be zero, if the user intend to send a trigger impulse it immediately after the orchestra instrument containing seqtime opcode. seqtime outputs a stream of zeroes except when a new time value stored in the table is reached. In this case the ktrig argument is filled with the time value, scaled according to current ktime_unit value. seqtime2 is similar to seqtime, the difference is that when ktrig_in contains a non-zero value, current index is reset to kinitndx value. kinitndx can be varied at performance time. trigseq accepts a trigger signal (ktrig_in) as input and outputs group of values (contained into kfn_values table) each time ktrig_in assumes a non-zero value. Each time a group of values is triggered, table pointer is advanced of a number of positions corresponding to the number of group-elements, in order to point to the next group of values. The number of elements of groups is determined by the number of koutX arguments. It is possible to start the sequence from a value different than the first, by assigning to initndx an index different than zero (which corresponds to the first value of the table). Normally the sequence is looped, and the start and end of loop can be adjusted by modifying kstart and kloop arguments. User must be sure that values of these arguments (as well as initndx) correspond to valid table numbers, otherwise Csound will crash (because no range-checking is implementeted). It is possible to disable loop (one-shot mode) by assigning the same value both to kstart and kloop arguments. In this case, the last read element will be the one corresponding to the value of such arguments. Table can be read backward by assigning a negative kloop value. Notice that trigseq output arguments are placed at the left of the opcode name, differently from usual (this style is already used in other opcodes using undefined lists of output arguments such as fin). trigseq is designed to be used together with seqtime or trigger opcodes. Example: instr 1 icps cpsmidi iamp ampmidi 5000 ktrig seqtime 1, 1, 10, 0, 1 trigseq ktrig, 0, 10, 0, 2, kdur, kampratio, kfreqratio schedkwhen ktrig, -1, -1, 2, 0, kdur, kampratio*iamp, kfreqratio*icps endin Random Curve Generators kr jspline kamp, kcpsMin, kcpsMax ar jspline xamp, kcpsMin, kcpsMax kr rspline krangeMin, krangeMax, kcpsMin, kcpsMax ar rspline xrangeMin, xrangeMax, kcpsMin, kcpsMax DESCRIPTION Generate random spline curves INITIALIZATION no init args PERFORMANCE kr, ar - output signal xrangeMin, xrangeMax - range of values of random-generated points kcpsMin, kcpsMax - range of point-generation rate. Min and max limits are expressed in cps. xamp - amplitude factor jspline (jitter-spline generator) generates a smooth curve based on random points generated at [cpsMin, cpsMax] rate. This opcode is similar to randomi or randi or jitter, but segments are not stright lines, but cubic spline curves. Output value range is approximately > -xamp and < xamp. Actually, real range could be a bit greater, because of interpolating curves beetween each pair of random-points. rspline (random-spline-curve generator) is similar to jspline but output range is defined by means of two limit values. Also in this case, real output range could be a bit greater of range values, because of interpolating curves beetween each pair of random-points. At present time generated curves are quite smooth when cpsMin is not too different from cpsMax. When cpsMin-cpsMax interval is big, some little discontinuity could occurr, but it should not be a problem in most cases. Maybe the algorithm will be improved in next versions. These opcodes are better than jitter when user wants to "naturalize" or "analogize" digital sounds. They could be used also in algorithmic composition, to generate smooth random melodic lines when used together with samphold opcode. Note that the result is quite different from the one obtained by filtering white noise, and allows the user to obtain a much more precise control. Tables of Vectors vtablei indx, ifn, interp, ixmode, iout1 [, iout2, iout3, .... , ioutN ] vtablek kndx, kfn, kinterp, ixmode, kout1 [, kout2, kout3, .... , koutN ] vtablea andx, kfn, kinterp, ixmode, aout1 [, aout2, aout3, .... , aoutN ] vtable1k kfn, kout1 [, kout2, kout3, .... , koutN ] vtabi indx, ifn, iout1 [, iout2, iout3, .... , ioutN ] vtabk kndx, ifn, kout1 [, kout2, kout3, .... , koutN ] vtaba andx, ifn, aout1 [, aout2, aout3, .... , aoutN ] vtablewi indx, ifn, ixmode, inarg1 [, inarg2, inarg3 , .... , inargN ] vtablewk kndx, kfn, ixmode, kinarg1 [, kinarg2, kinarg3 , .... , kinargN ] vtablewa andx, kfn, ixmode, ainarg1 [, ainarg2, ainarg3 , .... , ainargN ] vtabwi indx, ifn, inarg1 [, inarg2, inarg3 , .... , inargN ] vtabwk kndx, ifn, kinarg1 [, kinarg2, kinarg3 , .... , kinargN ] vtabwa andx, ifn, ainarg1 [, ainarg2, ainarg3 , .... , ainargN ] DESCRIPTION Access to table of vectors INITIALIZATION and PERFORMANCE ixmode - index data mode. The default value is 0. == 0 index is treated as a raw table location, == 1 index is normalized (0 to 1). ifn, kfn - table number indx, kndx, andx - Index into f-table, either a positive number range matching the table length (ixmode = 0) or a 0 to 1 range (ixmode != 0). iout1...ioutN, kout1,,,koutN, aout1...aoutN - output vectors kinterp - interpolation flag: 0 -> non-interpolation , non-zero -> interpolation activated inarg1...inargN, kinarg1...kinargN, ainarg1...ainargN - input vectors These opocodes support read/write access to arrays of vectors (or arrays of arrays). These opcodes are useful in all cases in which one needs to access sets of values associated to unique indexes (for example, multi-channel samples, STFT bin frames, spectral formants, p-field based scores etc.) . The number of elements of each vector frame is automatically determined by the number of outN or inargN arguments, and must remain fixed for all indexes of each table. vtable (vector table) family of opcodes allows the user to switch beetween interpolated or non-interpolated output at k-rate by means of kinterp argument. vtable allows also to switch the table number at k-rate (but this is possible only when vector frames of each used table have the same number of elements, otherwise unpredictable results could occurr), as well as to choose indexing style (raw or normalized, see also ixmode argument of table opcode ). Notice that no wrap nor limit mode is implemented. So, if an index attempt to access to a zone not allocated by the table, Csound will probably crash. However this drawback can be easily avoided by using wrap or limit opcodes applied to indexes before using vtable, in order to correct eventual out-of-range values. Notice that vtable output arguments are placed at the left of the opcode name, differently from usual (this style is already used in other opcodes using undefined lists of output arguments such as fin or trigseq). vtable1k is a reduced version of vtablek, it only allows to access the first vector (it is equivalent to vtablek with kndx = zero, but a bit faster). It is useful to easily and quickly convert a set of values stored in a table into a set of k-rate variables to be used in normal opocods. vtablew family allows to write vectors frames into tables. It allows to switch the table number at k-rate (but vector frames of each used table must have the same number of elements), as well as to choose indexing style (raw or normalized, see also argument ixmode in table opcode). vtab family is similar to vtable, but is much faster because interpolation is not available, table number cannot be changed after initialization, and only raw indexing is supported. vtabw family is similar to vtablew, but is much faster because interpolation is not available, table number cannot be changed after initialization, and only raw indexing is supported. Common Musical Converters octave(x) semitone(x) cent(x) db(x) DESCRIPTION Convert musical logarithmic units into multipliers. Useful to easily managing common musical unit of measure. INITIALIZATION and PERFORMANCE x - input value (can be at any rate). All these functions convert a logarithmic value to be used in multiplication. Standard musical unit of measure are supported: octave intervals semitone intervals cent intervals decibels The argument within the parentheses may be a further expression. These are really value converters with a special function of manipulating musical data. for exampe, if one wants to rise the amplitude of asig of 6 decibel it is sufficient the following line asig = asig * db(6) Also negative values are allowed, for example, if one has to transpose a frequency signal kfreq down of 7 semitones: kfreq = kfreq * semitone(-7) Glissando Generators kr lineto ksig, ktime kr tlineto ksig, ktime, ktrig DESCRIPTION Generate glissandos starting from a control signal. PERFORMANCE kr - output signal ksig - input signal ktime - time length of glissando in seconds ktrig - trigger signal lineto adds glissando (i.e. stright lines) to a stepped input signal (for example, produced by randh, randomh or lpshold). It generates a stright line starting from previous step value, reaching the new step value in ktime seconds. When the new step value is reached, such value is holded until a new step occurs. Be sure that ktime argument value is smaller than the time elapsed beetween two consecutive steps of the original signal, otherwise discontinuities will occurr in output signal. When used together with the output of lpshold it emulates the glissando effect of old analog sequencers. tlineto is similar to lineto, but can be applied to any kind of signal (not only stepped signals), without producing discontinuities. Last value of each segment is sampled and holded from input signal each time ktrig value is set to a nonzero value. Normally ktrig signal consists of a sequence of zeroes (see trigger opcode). The effect of glissando is quite different from port, since in these cases, the lines are stright. Also the context of useage is different. Converting RGB Image Data to Control Signals iwidth, iheight, ibpp bmopen ifilno,ihandle [,iflag] iwidth, iheight, ibpp bminfo ifilno kr, kg, kb, ka bmtable kx, ky, ihandle kr, kg, kb, ka bmtablei kx, ky, ihandle kr, kg, kb, ka bmoscil ktrig, kxinc, kyinc, ktrig_xphreset, ktrig_yphreset, kxphs, kyphs, ihandle kr, kg, kb, ka bmoscili ktrig, kxinc, kyinc, ktrig_xphreset, ktrig_yphreset, kxphs, kyphs, ihandle khue, ksat, kval, klum rgb2hsvl kred, kgreen, kblue ihue, isat, ival, ilum rgb2hsvl_i ired, igreen, iblue bmscan kx, ihorLines, ihandle, istartLine, ifnR, ifnG, ifnB bmscani kx, ihorLines, ihandle, istartLine, ifnR, ifnG, ifnB DESCRIPTION Generate control signals by scanning RGB image data. INITIALIZATION iwidth - image width iheight - image height ibpp - image bit per pixel ifilno - character-string denoting the file name of the source image. ihandle - handle value (an integer number) that univocally references to corresponding image, used by further opcodes that access to that image. It must be provided by the user iflag - packs the image data in different formats: 0 = array of rows and BGR (for paintlib processing and OpenGL without processing), 1 = array of raw bytes and RGB (for OpenGL with image processing), 2 = both. ihue, isat, ival, ilum - hue, saturation, value and luminance of current RGB data. ired, igreen, iblue - RGB components of a pixel. ihorLines - distance between horizontal lines of RGB image to scan. Minimum value is 1 maximum value is the vertical pixel size of the image istartLine - horizontal line to start with. Minimum is 0 (lowest horizontal line), maximum is the vertical size of the image in pixel, minus one. ifnR, ifnG, ifnB - numbers of output tables. Each table contains a vector with the single color component (Red, Green or Blue) of all horizontal scanned lines. PERFORMANCE kx - horizontal phase value ky - vertical phase value kr, kg, kb,ka - control signals containing the red, green, blue and alpha components of current pixel of the image. ktrig - trigger signal: when this signal is nonzero, forces the corresponding opcode to evaluate a new phase value, basing on kxinc kxinc, kyinc - horizontal and vertical phase increments. When ktrig is nonzero, new phase values are evaluated. ktrig_xphreset, ktrig_yphreset - when non-zero set current phase value to current value of kxphs and kyphs. kxphs, kyphs - control signals used to reset current horizontal and vertical phases when ktrig_xphreset and ktrig_yphreset are non-zero. khue, ksat, kval, klum - hue, saturation, value and luminance of current RGB data. kred, kgreen, kblue - RGB components of a pixel These opcodes allow to convert RGB image data to control signals, which can then be used to control any synthesis parameter of Csound instruments. bmopen read a RGB image file and stores it into memory. User should provide a unique identifier of the image (an integer number to be put in ihandle argument) to access it with the other RGB-oriented opcodes later. bmopen outputs information about opened image (width, height and bit per pixels). At present time the following image formats are supported: Windows Bitmap (.BMP) Tagged Image File Format (.TIF) Jpeg - Jfif Compliant (.JPG) Truevision Targa (.TGA) Portable Network Graphics (.PNG) Zsoft Paintbrush (.PCX) Macintosh PICT (.PCT) Encapsulated Postscript Bitmap (.EPS) Even if JPEG format is provided, it is not recommended to use files encoded with destructive compression algorithm, because this could provide distorsion of generated signals. iflag argument allows the user to set the way in which data is packed into memory: 0 is in BGR format (for bmscan family of opcodes and OpenGL without processing), 1 in RGB format (for use with img processing opcodes and OpenGL GLimg2tex opcode) , 2 both formats. Default value is 0. bminfo returns the width, height and the number of bits per pixel of an RGB image file, without storing it into memory. bmtable returns red, green, blue and alpha values of the pixel pointed by the kx and ky coordinates of the picture ihandle. bmtablei is identical to bmtable, but linear interpolation is provided when giving fractional coordinate values, whereas bmtable truncates any fractional value. bmoscil is a sort of a two-dimensional oscillator applied to RGB picture ihandle. Frequency/period of both horizontal and vertical domain can be independently set and varied during performance by means of kxinc (horizontal phase increment) and kyinc (vertical phase increment), that express the number of pixel that horizontal and vertical phases have to advance. Notice that the phases are incremented only when ktrig is set to non-zero values, allowing rhythmic effects. Phase increments can be fractional. Also, phases can be reinitialized, according to kxphs and kyphs when two other triggers (ktrig_xphreset, ktrig_yphreset) are set to non-zero values. bmoscili is identical to bmoscil, except linear interpolation is provided for output. rgb2hsvl and rgb2hsvl_i convert input RGB data to hue, saturation, value and luminance data. rgb2hsvl works at k-rate, rgb2hsvl_i at init-rate (luminance is different from value in that, while the last one expresses the maximum value between red, green, blue components of a given pixel, luminance expresses the sum of red, green and blue components). bmscan conception is similar to bmtable, but, instead of outputting scalar signals, it outputs vectors of RGB data, that are directly stored into tables. bmscan only accepts the horizontal coordinates as input (kx), because several vertical values aligned to the same horizontal position are stored in the output tables (ifnR, ifnG, ifnB) at the same time. These tables must be allocated before using bmscan opcode, by using a GEN routine, for example GEN02. ihandle is the RGB image identifier, ihorLines determines the distance beween horizontal scanned lines (if it is set to 1, all adjacent lines are scanned), values greater than one allow to hop any number of lines. istartLine allows to start with a line different from the bottom line (value 0). bmscan is designed to operate together with opcodes accepting vectorial signals as input (such as, for example, adsynt or adsynt2, whose input are tables containing variant amplitudes and frequencies provided to control a bank of oscillators). bmscani is identical to bmscan, exept that linear interpolation is provided for horizontal lines. All these opcodes are intended to be applied to hand-made images (that in this case would be a sort of graphical score), as well as to algorithmically generated images (Fractals, Cellular Automata, etc.). Notice that color black is treated as zero level, were amplitude increases when the values of each component increase. Trigger Metronome ktrig metro kfreq [, initphase] DESCRIPTION Generate a metronomic signal to be used in any circumstance an isochronous trigger is needed. INITIALIZATION initphase - initial phase value (in the 0 to 1 range) PERFORMANCE ktrig - output trigger signal kfreq - frequency of trigger bangs in cps metro is a simple opcode that outputs a sequence of isochronous bangs (that is 1 values) each 1/kfreq seconds. Trigger signals can be used in any circumstance, mainly to temporize realtime algorithmic compositional structures. Mandelbrot Set kiter, koutrig mandel ktrig, kx, ky, kmaxIter DESCRIPTION Returns the number of iterations corresponding to a given point of complex plane by applying the Mandelbrot set formula. PERFORMANCE kiter- number of iterations koutrig - output trigger signal ktrig - input trigger signal kx, ky - coordinates of a given point belonging to the complex plane kmaxIter - maximum iterations allowed mandel is an opocode that allows to use the Mandelbrot set formula to generate an output that can be applied to any musical (or non-musical) parameter. It has two output arguements, kiter, that contains the iteration number of a given point, and koutrig, that generates a trigger bang each time kiter changes. A new number of iterations is evaluated only when ktrig is set to a non-zero value. User have to set the coordinates of the complex plane inside kx and ky arguments, while kmaxIter contains the maximum number of iteration the user intend to use. Output values, that are integer numbers, can be mapped in any sorts of ways by the composer. Micro Tuning cpstun, cpstuni kcps cpstun ktrig, kindex, kfn icps cpstuni index, ifn INITIALIZATION icps - return value in cps index - an integer number denoting an index of scale ifn - function table containing the parameters (numgrades, interval, basefreq, basekeymidi) and the tuning ratios. PERFORMANCE kcps - return value in cps ktrig - a trigger signal used to trigger the evaluation kindex - an integer number denoting an index of scale kfn - function table containing the parameters (numgrades, interval, basefreq, basekeymidi) and the tuning ratios. These opcodes are similar to cpstmid, but work without necessity of MIDI. cpstun works at k-rate, while cpstuni at init-rate. They allow fully customized micro-tuning scales. They requires a function table number containing the tuning ratios, and some other parameters stored in the function table itself. kindex and index arguments should be filled with integer numbers expressing the grade of given scale to be converted in cps. In cpstun, a new value is evaluated only when ktrig contains a non-zero value. The function table ifn (or kfn) should be generated by GEN2 and the first four values stored in this function are parameters that express: numgrades (the number of grades of the micro-tuning scale), interval (the frequency range covered before repeating the grade ratios, for example 2 for one octave, 1.5 for a fifth etcetera), basefreq (the base frequency of the scale in cps), basekey (the integer index of the scale to which to assign basefreq unmodified). After these four values, the user can begin to insert the tuning ratios. For example, for a standard 12-grade scale with the base-frequency of 261 cps assigned to the key-number 60, the corresponding f-statement in the score to generate the table should be: ; numgrades basefreq tuning-ratios (eq.temp) ....... ; interval basekey f1 0 64 -2 12 2 261 60 1 1.059463 1.12246 1.18920 ..etc... Another example with a 24-grade scale with a base frequency of 440 assigned to the key-number 48, and a repetition interval of 1.5: ; numgrades basefreq tuning-ratios ....... ; interval basekey f1 0 64 -2 24 1.5 440 48 1 1.01 1.02 1.03 ..etc... Operations Between a Vectorial and a Scalar Signal vadd, vmult, vpow, vexp vadd ifn, kval, ielements vmult ifn, kval, ielements vpow ifn, kval, ielements vexp ifn, kval, ielements DESCRIPTION Perform numerical operations between a vectorial control signal and a scalar control signal INITIALIZATION ifn - number of the table hosting the vectorial signal to be processed ielements - number of elements of the vector PERFORMANCE kval - scalar operand to be processed These opcodes perform numeric operations between a vectorial control signal (hosted by the table ifn), and a scalar signal (kval). Result is a new vector that overrides old values of ifn. All these opcodes work at k-rate. vadd adds kval operand to each elements of the vector contained in the table ifn. vmult multiply each elements of the vector contained in the table ifn by kval operand. vpow rises each elements of the vector contained in the table ifn to kval power. vexp rises kval to each element contained in the table ifn. In all previous opcodes, resulting vectors are stored in ifn, overriding the intial vectors. If you want to keep initial vector, use vcopy opcode to copy it in another table. All these operators are designed to be used together with other opcodes that operate with vectorial signals such as bmscan, vcella, adsynt, adsynt2 etc. Operations Between Two Vectorial Signals vaddv ifn1, ifn2, ielements vsubv ifn1, ifn2, ielements vmultv ifn1, ifn2, ielements vdivv ifn1, ifn2, ielements vpowv ifn1, ifn2, ielements vexpv ifn1, ifn2, ielements vcopy ifn1, ifn2, ielements vmap ifn1, ifn2, ielements DESCRIPTION Performs numerical operations between two vectorial control signals INITIALIZATION ifn1 - number of the table hosting the first vector to be processed ifn2 - number of the table hosting the second vector to be processed ielements - number of elements of the two vectors These opcodes perform operations between two vectorial control signals, that is, each element of the first vector is processed (only) with the corresponding element of the other vector. Each vectorial signal is hosted by a table (ifn1 and ifn2). The number of elements contained in both vectors must be the same. Result is a new vectorial control signal that overrides old values of ifn1. If you want to keep old ifn1 vector, use vcopy opcode to copy it in another table. All these opcodes work at k-rate. vaddv adds each element of ifn1 to the corresponding element of ifn2. vsubv subtracts each element of ifn2 from the corresponding element of ifn2. vmultv multiply each element of ifn1 by the corresponding element of ifn2. vdivv divide each element of ifn1 by the corresponding element of ifn2. vpowv rises each element of ifn1 to the corresponding element of ifn2. vexpv rises each element of ifn2 to the corresponding element of ifn1. vcopy copies ifn2 to ifn1. Useful to keep old vector values, by storing them in another table. vmap maps elements of ifn1 according to the values of table ifn2. Elements of ifn1 are treated as indexes of table ifn2, so element values of ifn1 must not exceed the length of ifn2 table otherwise a Csound crash due to an illegal memory access error will occurr. Elements of ifn1 are treated as integers, so any fractional part will be truncated. All these operators are designed to be used together with other opcodes that operate with vectorial signals such as bmscan, vcella, adsynt, adsynt2 etc. Limiting and Wrapping Vectorial Signals vlimit ifn, kmin, kmax, ielements vwrap ifn, kmin, kmax, ielements vmirror ifn, kmin, kmax, ielements DESCRIPTION Limit or wrap elements of vectorial control signals. INITIALIZATION ifn - number of the table hosting the vector to be processed ielements - number of elements of the vector PERFORMANCE kmin - minimum threshold value kmax - maximum threshold value vlimit set lower and upper limits on each element of the vector they process. vwrap wraps around each element of corresponding vector if it exceeds low or high thresholds. vmirror 'reflects' each element of corresponding vector if it exceeds low or high thresholds. These opcodes are similar to limit, wrap and mirror, but operate with a vectorial signal instead of with a scalar signal. Result overrides old values of ifn1, if these are out of min/max interval. If you want to keep input vector, use vcopy opcode to copy it in another table. All these operators are designed to be used together with other opcodes that operate with vectorial signals such as bmscan, vcella, adsynt, adsynt2 etc. Vectorial Envelope Generators vlinseg ifnout, ielements, ifn1, idur1, ifn2 [, idur2, ifn3 [...]] vexpseg ifnout, ielements, ifn1, idur1, ifn2 [, idur2, ifn3 [...]] DESCRIPTION Generate linear or exponential vectorial segments INITIALIZATION ifnout - number of table hosting output vectorial signal ifn1 - starting vector ifn2, ifn3, etc. - vector after idur1 seconds idur1 - duration in seconds of first segment. dur2, idur3, etc. - duration in seconds of subsequent segments. ielements - number of elements of vectors. These opcodes are similar to linseg and expseg, but operate with vectorial signals instead of with scalar signals. output is a vectorial control signal hosted by ifnout (that must be previously allocated), while each break-point of the envelope is actually a vector of values. All break-points must contain the same number of elements (ielements). All these operators are designed to be used together with other opcodes that operate with vectorial signals such as bmscan, vcella, adsynt, adsynt2 etc. Vectorial Random Signal Generator vrandh ifn, krange, kcps, ielements vrandi ifn, krange, kcps, ielements DESCRIPTION Generate a sort of 'vectorial band-limited noise' INITIALIZATION ifn - number of the table containing the output vector ielements - number of elements of output vector. PERFORMANCE krange - range of random elements (from -krange to krange) kcps - rate of generated elements in cycles per seconds These opcodes are similar to randh and randi, but operate with vectors instead of with scalar values. The output is a vector contained in ifn (that must be previously allocated). All these operators are designed to be used together with other opocdes that operate with vector such as bmscan, adsynt etc. Vectorial Control-rate Delay Paths vport ifn, khtime, ielements [, ifnInit] vecdelay ifn, ifnIn, ifnDel, ielements, imaxdel [, iskip] DESCRIPTION Generate a sort of 'vectorial' delay or portamento INITIALIZATION ifn - number of the table containing the output vector ifnIn - number of the table containing the input vector ifnDel - number of the table containing a vector whose elements contain delay values in seconds ifnInit (optional) - number of the table containing a vector whose elements contain intial portamento values. ielements - number of elements of vectors. imaxdel - Maximum value of delay in seconds. iskip (optional) - initial disposition of delay-loop data space (see reson). The default value is 0. PERFORMANCE khtime - time for output to reach halfway to input. vport is similar to port, but operates with vectorial signals, istead of with scalar signals. Each vector element is treated as an indipendent control signal. Input vector input and output vectors are placed in the same table and output vector overrides input vector. If you want to keep input vector, use vcopy opcode to copy it in another table. vecdelay is similar to vdelay, but it works at k-rate and, instead of delaying a single signal, it delays a vector. ifnIn is the input vector of signals, ifn is the output vector of signals, and ifnDel is a vector containing delay times for each element, expressed in seconds. Elements of ifnDel can be updated at k-rate. Each single delay can be different from that of the other elements, and can vary at k-rate. imaxdel sets the maximum delay allowed for all elements of ifnDel. K-rate Variable Time Delay kr, vdelayk ksig, kdel, imaxdel [, iskip, imode] DESCRIPTION Variable delay applied to a k-rate signal INITIALIZATION imaxdel - maximum value of delay in seconds. iskip (optional) - Skip initialization if present and non zero. imode (optional) - if non-zero it suppresses linear interpolation. While, normally, interpolation increases the quality of a signal, it should be suppressed if using vdelay with discrete control signals, such as, for example, trigger signals. PERFORMANCE kr - delayed output signal ksig - input signal kdel - delay time in seconds can be varied at k-rate vdelayk is similar to vdelay, but works at k-rate. It is designed to delay control signals, to be used, for example, in algorithmic composition. Cellular Automata vcella ktrig, kreinit, ioutFunc, initStateFunc, iRuleFunc, ielements, irulelen [, iradius] DESCRIPTION Unidimensional Cellular Automata applied to Csound vectors INITIALIZATION ioutFunc - number of the table where the state of each cell is stored initStateFunc - number of a table containig the inital states of each cell iRuleFunc - number of a lookup table containing the rules ielements - total number of cells irulelen - total number of rules iradius (optional) - radius of Cellular Automata. At present time CA radius can be 1 or 2 (1 is the default) PERFORMANCE ktrig - trigger signal. Each time it is non-zero, a new generation of cells is evaluated kreinit - trigger signal. Each time it is non-zero, state of all cells is forced to be that of initStateFunc. vcella supports unidimensional cellular automata, where the state of each cell is stored in ioutFunc. So ioutFunc is a vector containing current state of each cell. This variant vector can be used together with any other vector-based opcode, such as adsynt, vmap, vpowv etc. initStateFunc is an input vector containing the inital value of the row of cells, while iRuleFunc is an input vector containing the rules in the form of a lookup table. Notice that initStateFunc and iRuleFunc can be updated during the performance by means of other vector-based opcodes (for example vcopy) in order to force to change rules and status at performance time. A new generation of cells is evaluated each time ktrig contains a non-zero value. Also the status of all cells can be forced to assume the status corresponding to the contents of initStateFunc each time kreinit contains a non-zero value. Radius of CA algorithm can be 1 or 2 (optional iradius arguement). Table-Controlled Oscillator Bank ar adsynt2 kamp, kcps, iwfn, ifreqfn, iampfn, icnt[, iphs] Performs additive synthesis with an arbitrary number of partials, not necessarily harmonic (see adsynt for detailed manual). INITIALIZATION iwfn - table containing a waveform, usually a sine. Table values are not interpolated for performance reasons, so larger tables provide better quality. ifreqfn - table containing frequency values for each partial. ifreqfn may contain initial frequency values for each partial, but is usually used for generating parameters at runtime with tablew. Frequencies must be relative to kcps. Size must be at least icnt. iampfn - table containing amplitude values for each partial. iampfn may contain initial amplitude values for each partial, but is usually used for generating parameters at runtime with tablew. Amplitudes must be relative to kamp. Size must be at least icnt. icnt - number of partials to be generated iphs - initial phase of each oscillator, if iphs = -1, initialization is skipped. If iphs > 1, all phases will be initialized with a random value. PERFORMANCE kamp - amplitude of note. kcps - base frequency of note. Partial frequencies will be relative to kcps. adsynt2 is identical to adsynt (by Peter Neubäcker), except it provides linear interpolation for amplitude envelopes of each partial. It is a bit slower than adsynt, but interpolation higly improves sound quality in fast amplitude envelope transients when kr < sr (i.e. when ksmps > 1). No interpolation is provided for pitch envelopes, since in this case sound quality degradation is not so evident even with high values of ksmps. It is not recommended when kr=sr, in this case adsynt is better (since it is faster). adsynt2 is designed to be used together with bmscan, bmscani, vectorial generators, operators and modifiers, vcella, etc. Schedule events schedk ktrigger, kopcode, kp1 [,kp2 ,kp3, kp4, kp5, kp6, ...., kpN] Generate events from orchestra at k-rate. This opcode may be useful eg for certain kinds of algorithmic composition. INITIALIZATION no init-rate arguments PERFORMANCE ktrigger - trigger signal (see trigger and metro opcodes) kopcode - ascii code of the corresponding score opcode to be activated (for example, for the notes of score the ascii code of 'i' i.e. 105). Zero is the default and is equivalent to 'i' opcode, so you can use 0 or 105 obtaining the same result. kp1,kp2,..., kpN - p-fields passed to generated events This opcode is derived from schedkwhen (by Rasmus Ekman), but is simpler to use because has less arguments, is more specialized, and a bit faster. In fact it doesn't support arguments kmintime, kmaxinst, kinsnum etc. In the future it will also allow score opcodes different from 'i'. At present time only the 'i' opcode is supported (because I haven't tested the other score opcodes yet). Time Variant Sequencer ktrig timedseq ktimpnt, ifn, kp1 [,kp2, kp3, ...,kpN] DESCRIPTION An event-sequencer in which time can be controlled by a time-pointer. Sequence data are stored into a table. INITIALIZATION ifn - number of table containing sequence data PERFORMANCE ktrig - output trigger signal ktimpnt - time pointer into sequence file, in seconds. kp1,...,kpN - output p-fields of notes. kp2 meaning is relative action time and kp3 is the duration of notes in seconds. timedseq is a sequencer that allows to schedule notes starting from a user sequence, and depending from an external timing given by a time-pointer value (ktimpnt argument). User should fill table ifn with a list of notes, that can be provided in an external text file by using GEN23, or by typing it directly in the orchestra (or score) file with GEN02. The format of the text file containing the sequence is made up simply by rows containing several numbers separated by space (similarly to normal Csound score). The first value of each row must be a positve or null value, except for a special case that will be explained below. This first value is normally used to define the instrument number corresponding to that particular note (like normal score). The second value of each row must contain the action time of corresponding note and the third value its duration. This is an example: 0 0 0.25 1 93 0 0.25 0.25 2 63 0 0.5 0.25 3 91 0 0.75 0.25 4 70 0 1 0.25 5 83 0 1.25 0.25 6 75 0 1.5 0.25 7 78 0 1.75 0.25 8 78 0 2 0.25 9 83 0 2.25 0.25 10 70 0 2.5 0.25 11 54 0 2.75 0.25 12 80 -1 3 -1 -1 -1 <--- last row of the sequence In this example, the first value of each row is always zero (it is a dummy value, but this p-field can be used, for example, to express a MIDI channel or an instrument number), except the last row, that begins with -1. This value (-1) is a special value, that indicates the end of sequence. It has itself an action time, because sequnces can be looped. So the previous sequence has a default duration of 3 seconds, being value 3 the last action time of the sequence. It is important that ALL lines contains the same number of values (in the example all rows contains exactly 5 values). The number of values contained by each row, MUST be the number of kpXX output arguments (notice that, even if kp1, kp2 etc. are placed at the right of the opcode, they are output arguments, not input arguments). ktimpnt argument provide the real temporization of the sequence. Actually the passage of time through sequence is specified by ktimpnt itself, which represents the time in seconds. ktimpnt must always be positive, but can move forwards or backwards in time, be stationary or discontinuous, as a pointer into the sequence file, in the same way of pvoc or lpread. When ktimpnt crosses the action time of a note, a trigger signal is sent to ktrig output argument, and kp1, kp2,...kpN arguments are updated with the values of that note. This information can then be used with schedk or schedkwhen to actually activate note events. Notice that kp1,...kpn data can be further processed (for example delayed with delayk, transposed, etc.) before feeding schedk or schedkwhen. ktimepoint can be controlled by linear signal, for example: ktimpnt line 0,p3,3 ; orignal sequence duration was 3 secs ktrig timedseq ktimpnt,1,kp1,kp2,kp3,kp4,kp5 schedk ktrig, 105, 2, 0, kp3,kp4,kp5 in this case the complete sequence (with orginal duration of 3 seconds) will be played in p3 seconds. You can loop a sequence by contolling it with a phasor: kphs phasor 1/3 ktimpnt = kphs * 3 ktrig timedseq ktimpnt,1,kp1,kp2,kp3,kp4,kp5 schedk ktrig, 105, 2, 0, kp3,kp4,kp5 Obviously you can play only a fragment of the sequence, read it backward, and non-linearly access sequence data in the same way of pvoc and lpread opcodes. With timedseq opcode you can do almost all things of a normal score, except you have the following limitations: You can't have two notes exactly starting with the same action time; actually at least a k-cycle should separate timing of two notes (otherwise the schedk mechanism eats one of them). all notes of the sequence must have the same number of p-fields (even if they activate different instruments). You can remedy this limitation by filling with dummy values notes that belongs to instruments with less p-fields than other ones. Splitting a trigger signal into structured channels splitrig ktrig, kndx, imaxtics, ifn, kout1 [,kout2,...,koutN] DESCRIPTION Splits a trigger signal (i.e. a timed sequence of control-rate impulses) into several channels following a structure designed by the user. INITIALIZATION imaxtics - number of tics belonging to largest pattern ifn - number of table containing channel-data structuring PERFORMANCE ktrig - trigger i.e. master tic kndx - number of current pattern kout1,...,koutN - output channels containing splitted tics splitrig opcode splits a trigger signal into several output channels according to one or more patterns provided by the user. Normally the regular timed trigger signal generated by metro opcode is used to be transformed into rhythmic pattern that can trig several independent melodies or percussion riffs. But you can also start from non-isocronous trigger signals. This allows to use some "interpretative" and less "mechanic" groove variations. The scheme of patterns is defined by the user and is stored into ifn table according to the following format: gi1 ftgen 1,0,1024, -2 \ ; table is generated with GEN02 in this case \ ; numtics_of_pattern_1, \ ;pattern 1 tic1_out1, tic1_out2, ... , tic1_outN,\ tic2_out1, tic2_out2, ... , tic2_outN,\ tic3_out1, tic3_out2, ... , tic3_outN,\ ..... ticN_out1, ticN_out2, ... , ticN_outN,\ \ numtics_of_pattern_2, \ ;pattern 2 tic1_out1, tic1_out2, ... , tic1_outN,\ tic2_out1, tic2_out2, ... , tic2_outN,\ tic3_out1, tic3_out2, ... , tic3_outN,\ ..... ticN_out1, ticN_out2, ... , ticN_outN,\ ..... \ numtics_of_pattern_N,\ ;pattern N tic1_out1, tic1_out2, ... , tic1_outN,\ tic2_out1, tic2_out2, ... , tic2_outN,\ tic3_out1, tic3_out2, ... , tic3_outN,\ ..... ticN_out1, ticN_out2, ... , ticN_outN,\ This scheme can contain more than one pattern, each one with a different number of rows. Each pattern is preceded by a a special row containing a single numtics_of_pattern_N field; this field expresses the number of tics that makes up the corresponding pattern. Each pattern's row makes up a tic. Each pattern's column corresponds to a cannel, and each field of a row is a number that makes up the value outputted by the corresponding koutXX channel (if number is a zero, corresponding output channel will not trigger anything in that particular arguments). Obviously, all rows must contain the same number of fields that must be equal to the number of koutXX channel. All patterns must contain the same number of rows, this number must be equal to the largest pattern and is defined by imaxtics variable. Even if a pattern has less tics than the largest pattern, it must be made up of the same number of rows, in this case, some of these rows, at the end of the pattern itself, will not be used (and can be set to any value, because it doesn't matter). kndx variable chooses the number of the pattern to be played, zero indicating the first pattern. Each time the integer part of kndx changes, tic counter is reset to zero. Patterns are looped and each numtics_of_pattern_N the cicle is repeated. Recording and playing-back control signals tabrec ktrig_start, ktrig_stop, knumtics, kfn, kin1 [,kin2,...,kinN] tabplay ktrig, knumtics, kfn, kout1 [,kout2,..., koutN] DESCRIPTION Record and playback control-rate signals on trigger-temporization basis. INITIALIZATION no i-rate arguments PERFORMANCE ktrig_start - start recording when non-zero ktrig_stop - stop recording when knumtics trigger impulses are received by this input argument knumtics - stop recording or reset playing pointer to zero when the number of tics defined by this argument is reached kfn - table where k-rate signals are recorded kin1,...,kinN - input signals to record ktrig - starts playing when non-zero kout1,...,koutN - playback output signals tabrec and tabplay opcodes allow to record/playback control signals on trigger-temporization basis. tabrec opcode records a group of k-rate signals by storing them into kfn table. Each time ktrig_start is triggered, tabrec resets the table pointer to zero and begins to record. Recording phase stops after knumtics trigger impluses have been received by ktrig_stop argument. tabplay plays back a group of k-rate signals, previously recorded by tabrec into a table. Each time ktrig argument is triggered, an internal counter is increased of one unit. After knumtics trigger impluses are received by ktrig argument, the internal counter is zeroed and playback is restarted from the beginning, in looping style. These opcodes can be used like a sort of "middle-term" memory that "remembers" generated signals. Such memory can be used to supply generative music with a coherent iterative compositional structure. One-dimensional HVS vphaseseg kphase, ioutab, ielems, itab1,idist1,itab2 [,idist2,itab3,...,idistN-1,itabN] GLvphaseseg kphase, ioutab, ielem, itab1,idist1,itab2 [,idist2,itab3,...,idistN-1,itabN] DESCRIPTION Allow one-dimensional HVS (Hyper-Vectorial Synthesis). INITIALIZATION ioutab - number of output table ielem - number of elements of tables itab1,...,itabN - breakpoint table numbers idist1,...,idistN-1 - distances between breakpoints in percentage values PERFORMANCE kphase - phase pointer vphaseseg returns the coordinates of the section points of an N-dimensional space path. The coordinates of the section points are stored into an output table. The number of dimensions of the N-dimensional space is determined by ielem argument that is equal to N and can be set to any number. To define the path, user have to provide a set of points of the N-dimensional space, called break-points. Each of these points has N coordinates. The coordinates of each of these break-points must be contained in a different table. The number of coordinates to insert in each break-point table is obviously equal to the ielem argument. There can be any number of break-point tables filled by the user. In other words, the Hyper Vectorial Synthesis is used for morphing a parameter set according to a user path. Hyper-Vectorial Synthesis actually deals with two kinds of spaces. The first space is the N-dimensional space in which the path is defined, this space is called time-variant parameter space (or SPACE A). The path belonging to this space is covered by moving a point into the second space that normally has a number of dimensions smaller than the first. Actually, the point in motion is the projection of corresponding point of the N-dimensional space (could also be considered a section of the path). The second space is called user-pointer-motion space (or SPACE B) and, in the case of vphaseseg opcode, has only ONE DIMENSION. Space B is covered by means of kphase argument (that is a sort of path pointer), and its range is 0 to 1. The output corresponding to current pointer value is stored in ioutab table, whose data can be afterwards used to control any syntesis parameters. In vphaseseg, each break-point is separated from the other by a distance expressed in percentage, where all the path length is equal to the sum of all distances. So distances between breakpoints can be different, differently from kinds of HVS in which space B has more than one dimension, in these cases distance between break-points MUST be THE SAME for all intervals. ZAK space read access inside expressions iout = zr(iIndex) kout = zr(kIndex) aout = zr(aIndex) DESCRIPTION Allow to read ZAK space inside expressions. These opcodes are identical to zir, zkr and zar, but can be used in function fashion. Rate Converters kvar = k(ivar) avar = a(kvar) tvar = t(kvar) kvar = k(tvar) tabk2t itab_out, itab_in, ielem [, istart_ndx] set_t_del idelay INITIALIZATION ivar - input variable itab_out - output table number itab_in - input table number ielem - number of table elements istart_ndx (optional) - starting element index idelay - maximum delay in frames PERFORMANCE kvar, avar - converted variable FRAME-RATE PERFORMANCE tvar - converted variable working at frame-rate k(ivar) converts an i-rate variable to a k-rate variable. It is mainly used to get the proper rate from functions inside expressions, for example, if somebody needs rnd(1) to work at k-rate, he can write rnd(k(1)). a(kvar) converts a k-rate variable to an a-rate variable. t(kvar) converts a k-rate variable to a frame-rate variable. It is very useful when generating both audio and animated graphics in the same CsoundAV session. k(tvar) converts a t-rate variable to a k-rate variable. At present time no buffering is implemented, so k-rate signal updating timing could not be accurate. Notice that, when audio output is suppressed (-+Y flag) there is no need of conversion. tabk2t converts table data updated at k-rate to data updated at frame-rate. Output is stored into itab_out table, itab_in table is left unaffected. set_t_del opcode sets the maximum number of frames with which data converted from k-rate to frame-rate should be delayed. If animations don’t run smoothly, try to increase this delay. However, the more this delay increases, the less audio will syncrhonized with video. CsoundAV is started with a default delay value of 10. IMPORTANT: I remember that frame-rate cannot be polluted with k-rated expression, otherwise discontinuities can occurr in animation flow (this happens only when generating audio, however, if user suppresses audio (-+Y flag), it is possible to mix k-rate with frame-rate variables in any case, eliminating the previous restriction). Notice that idelay argument of set_t_del opcode represents the maximum delay, expressed in frames. Due to audio buffering jitter, actual delay of video animation can be a random number between 1 and idelay frames. So synchronization of audio with graphics will have a variant accuracy, depending on both audio buffer and idelay sizes. Obviously, the optimum would be to reduce audio buffer and idelay to minimum possible values, avoiding buffer underrun that could introduce drop-outs and irregularities in animation flow. However in real cases it is not possible to have a perfect syncronization of audio and graphics: this drawback is noticeable with percussive sounds associated with fast graphics changes. A way to improve syncronization is to run two separate instances of DirectCsound at the same time, the first running only graphics and the second only sound. A third program, (for example, a MIDI sequencer, or a third instance of Csound outputting only MIDI events) would control the event scheduling of both csound instances. Table Read Access inside expressions tb0_init ifn tb1_init ifn .... tb15_init ifn iout = tb0(iIndex) kout = tb0(kIndex) iout = tb1(iIndex) kout = tb1(kIndex) .... iout = tb15(iIndex) kout = tb15(kIndex) DESCRIPTION Allow to read tables in function fashion, to be used inside expressions At present time Csound only supports functions with a single input argument. However, to access table elements, user must provide two numbers, i.e. the number of table and the index of element. So, in order to allow to access a table element with a function, a previous preparation step should be done. There are 16 different opcodes whose name is associated with a number from 0 to 15. User can associate a specific table with each opcode (so the maximum number of tables that can be accessed in function fashion is 16). Prior to access a table, user must associate the table with one of the 16 opcodes by means of an opcode chosen among tb0_init...tb15_init. For example, tb0_init 1 associates table 1 with tb0( ) function, so that, each element of table 1 can be accessed (in function fashion) with: kvar = tb0(k_some_index_of_table1) * k_some_other_var ivar = tb0(i_some_index_of_table1) + i_some_other_var etc... By using these opcodes, user can drastically reduce the number of lines of an orchestra, improving its readability. Accessing Spectral Data Types ipoints, iminfreq, imaxfreq specinfo wsig spec2tab wsig, ifnout, kfilter [, istartoffset, inumelem] DESCRIPTION Allow to access spectral signals (w-type) to use their data with k-rate or frame-rate opcodes INITIALIZATION ipoints - number of frequencial points of spectrum iminfreq, imaxfreq - lowest and highest frequency of analysis ifnout - number of output table in which converted data will be stored istartoffset (optional) - offset of starting frequency to be converted. Default value is 0 inumelem (optional) - number of frequency points to be converted. Default value is equal to the number of frequencies of wsig PERFORMANCE wsig - spectral input signal kfilter - filter to smooth fast spectrum transients specinfo returns some information about a w-type spectral signal. This information can be used to set-up further processing with spectral data converted by spec2tab opcode. spec2tab convert wsig (a w-type signal) into a time-variant vector stored in ifnout (a normal Csound table). Data contained by this table can then accessed by normal Csound opcodes, (for example, table, tab, tb0( ) etc.) or further processed by means of vectorial math operators and functions (for example vadd, vmult, vpow, vsubv etc.), and used to control any synthesis parameter. Spectral data contained in can also be used to control graphic animations. In this case, if both audio and graphics are used in the same Csound session, the rate at which ifnout table is updated (that is k-rate) must be converted to frame-rate by means of tabk2g opcode (see corresponding documentation). Converted data is filtered to smooth fast transients, and filter cutoff frequency can be adjusted with kfilter argument. It is also possible to skip some analyzed frequency of spectrum by means of istartoffset and inumelem arguments Utility Opcodes exitnow turnoffk ktrig ktrig changed kvar1 [, kvar2,..., kvarN] system “commandLine” klen = ftlen(ktabnum) kout Trandom ktrig, min, max kout max_k asig, ktrig, itype DESCRIPTION Some utilities for various tasks. exitnow immediately exits Csound program, at any point it is called. It could be useful for batch processing. turnoffk turns of current instrument when ktrig argument is triggered. changed opcode outputs a trigger signal that informs when one (or several ones) of its k-rate arguments has changed. Useful with valuator widgets or MIDI controllers. system opcode transfers a command to the underlying shell. The command is passed by means of “commandLine” argument in the form of a double-quoted text string. N.B. Windows/DOS command-line shell is not able to recognize “/” character as directory separator for pathnames. On the other hand, it is not possible to use “\” in the “commandLine” string, because it will be rejected by Csound parser (that interprets it as a line-break separator). For now, the solution is to write a .bat file containing any complex command line, and placing it into a directory located in the PATH environment variable. ftlen(ktab) is identical to normal ftlen( ), but works at k-rate (whereas regular ftlen( ) only works at init-rate). It is useful when different tables of various length are passed as argument at different times in the same activated note. This could happen, for example, in algorithmic generation or generative music made inside Csound itself. Trandom is almost identical to random opcode, except Trandom updates output with a new random value only when ktrig argument is triggered. max_k outputs the local maximum (or minimum) value of the incoming asig signal, checked in the time interval between ktrig has become true twice. iflag determinates the behaviour of max_k: 1 - absolute maximum (sign of negative values is changed to positive before evaluation) 2 - actual maximum 3 - actual minimum 4 - calculate average value of asig in the time interval This opcode can be useful in several situations, for example to implement a vu-meter Saving and Loading Tables from file ftsave "filename", iflag, ifn1 [,ifn2,...ifnX] ftsave_k "filename", ktrig, iflag, ifn1 [,ifn2,...ifnX] ftload "filename", iflag, ifn1 [,ifn2,...,ifnX] ftload_k "filename", ktrig, iflag, ifn1 [,ifn2,...,ifnX] DESCRIPTION Save and load a set of previously-allocated tables to/from a file. INTIALIZATION "filename" - quoted string containing the name of the file where load/save the tables. If the string is "BROWSE_FILE", a file browser dialog box will appear, allowing the user to type/choose the file name at performance time. iflag - type of the file to load/save: zero = binary file, nonzero = text file ifn1, ifn2,...ifnX - numbers of tables to load/save PERFORMANCE ktrig - trigger signal. Save/load file each time it is nonzero. ftsave and ftload allow to save and re-load a list of tables. Such tables have to be already allocated. The format can be binary or text; binary format is not compatible with wavefiles, and is not endian-safe, at least for now. ftsave_k and ftload_k are identical to ftsave and ftload. The only difference is saving/loading operation can be repeated several times in the same note, according to the trigger signal. Browsing files A new feature was implemented for quoted strings. If the quoted string is "BROWSE_FILE", a file chooser dialog box will appear, allowing to browse a file. The actual file name is then substituted to the quoted string. It works with (almost) all opcodes containing a quoted-string argument, for example, soundin, diskin, ftsave, ftload, FLsavesnap, FLloadsnap, bmopen, etc..), actually all opcodes that contain unquote( ) function. Copying a table to another table vcopy_i ifn1, ifn2, ielements INITIALIZATION ifn1 - destination table ifn2 - source table ielements - number of elements to copy. This value must be <= to the size of both tables. This opcode is identical to vcopy but works at init-rate only. Radio Baton Opcodes rbatonPercPad kDur, kStick1instr, kStick2Instr, kFootSw1dn, kFootSw1up, kFootSw2dn, kFootSw2up, kButtonInstr kx1, ky1, kz1, kx2, ky2, kz2 rbatonXYZ kpot1, kpot2, kpot3, kpot4, kfsw1, kfsw2, kbutton rbatonPot DESCRIPTION Helper opcodes for the Radio Baton hardware by Max Mathews. These opcodes transform the Radio Baton into a simple Csound control surface. They allow to directly get and use the MIDI data incoming from the Radio Baton. If you don't own a Radio Baton, ingore these opocodes. INTIALIZATION No initialization arguments PERFORMANCE kDur - determines the duration of the notes activated by the whacks of the two sticks and by the pedals and the B15+ button. kStick1instr, kStick2Instr - the numbers of the instruments to be activated, respectively, with the whaks of stick 1 and stick 2. These arguments can be changed at k-rate, allowing to modify the number of the activated instruments during the performance. The pfields of such instruments will be got from the following radio baton states: p1 (instr number) = the value provided to the kStick1instr and/or kStick2instr arguments p2 (action time) = always zero (this means that it is immediately switched on) p3 (duration) = is set to current kDur value. p4 = stick whack strenght (normalized in the 0 to 1 range) p5 = X coordinate at the moment of the stick whack p6 = Y coordinate a the moment of the stick whack p7 - is set to current position of pot 1 of the Radio Baton (normalized in the 0 to 1 range. Pots 0 and 4 are not used). p8 - is set to current position of pot 2 of the Radio Baton (normalized in the 0 to 1 range). p9 - is set to current position of pot 3 of the Radio Baton (normalized in the 0 to 1 range). kFootSw1dn - determines the behavior of the foot switch 1 when it is switched down. If it is set to a positive integer number, it will schedule a note of an instrument having its number = iFootSw1dn. The pfields of such instrument will be got from the following radio baton states: p1 (instr number) = the value provided to the iFootSw1dn argument p2 (action time) = always zero (this means that it is immediately switched on) p3 (duration) = this value depends on the value assigned to iFootSw1up (that is the next argument of this opcode). If iFootSw1up has been set to zero, then p3 is set to a negative number (that starts a held note; this behavior can be inverted for pedals having opposite polarity, see below), else p3 is set to current kDur value. p4 - is set to current position of pot 1 of the Radio Baton (normalized in the 0 to 1 range. Pots 0 and 4 are not used). p5 - is set to current position of pot 2 of the Radio Baton (normalized in the 0 to 1 range). p6 - is set to current position of pot 3 of the Radio Baton (normalized in the 0 to 1 range). If it is set to zero, see the explanation of the next argument (iFootSw1up). kFootSw1up - determines the behavior of the foot switch 1 when it is switched up. If it is set to a positive integer number, it will schedule a note of an instrument having its number = iFootSw1up. The pfields of such instrument will be got from the following radio baton states: p1 (instr number) = the value provided to the iFootSw1up argument p2 (action time) = always zero (this means that it is immediately switched on) p3 (duration) = this value depends on the value assigned to iFootSw1dn (that is the previous argument of this opcode). If iFootSw1dn has been set to zero, then p3 is set to a negative number (that starts a held note), else p3 is set to current kDur value. p4 - is set to current position of pot 1 of the Radio Baton (normalized in the 0 to 1 range. Pots 0 and 4 are not used). p5 - is set to current position of pot 2 of the Radio Baton (normalized in the 0 to 1 range). p6 - is set to current position of pot 3 of the Radio Baton (normalized in the 0 to 1 range) . kFootSw2dn, kFootSw2up - these arguments behaves in identical way of iFootSw1dn, iFootSw1up, but refer to the foot switch 2 of the Radio Baton. See previous explanation for details. kButtonInstr - determines the behavior of the B15+ button of the Radio Baton when it is pressed. If it is set to a positive integer number, it will schedule a note of an instrument having its number = kButtonInstr. The pfields of such instrument will be got from the following radio baton states: p1 (instr number) = the value provided to the iButton argument p2 (action time) = always zero (this means that it is immediately switched on) p3 (duration) = is set to current kDur value. p4 - is set to current position of pot 1 of the Radio Baton (normalized in the 0 to 1 range. Pots 0 and 4 are not used). p5 - is set to current position of pot 2 of the Radio Baton (normalized in the 0 to 1 range). p6 - is set to current position of pot 3 of the Radio Baton (normalized in the 0 to 1 range). The B15+ button is unable to send a switch-off message when you release it, differently from the two foot switches. It only retrieves a value when is pressed. Notice that the B15+ button seems not to function when a mono jack is inserted in the B15- inlet (that of the foot-switch 1, the same thing happens with the B14- inlet and the B14+ button, that, anyway, cannot be used for performance). Curiously, I noticed that if you use a stereo jack, both the B15- pedal and the the B15+ button are active an functional at the same time. So I placed a stereo jack adapter to the mono jack of my pedals, in order to have the B14+ and B15+ buttons to function properly when the pedals are inserted. I don't know if this issue is only present on my Radio Baton (revision #55) or in all other Radio Batons. kx1, ky1, kz1 - the spatial coordinates (X, Y and Z) of current position of stick 1. The values are normalized in the 0 to 1 range. kx2, ky2, kz2 - the spatial coordinates (X, Y and Z) of current position of stick 2 .The values are normalized in the 0 to 1 range. kpot1, kpot2, kpot3, kpot4 - current values of pot1, pot2, pot3 and pot4.The values are normalized in the 0 to 1 range. kfsw1, kfsw2 - the status of the two foot switches. A 1 indicates that corresponding pedal is pressed, a zero that it is depressed. kbutton - it is normally zero. It assumes 1 when the B15+ button is pressed. Then it returns instantly to zero. rbatonPercPad allows to play a note when the Radio Baton pad is hit with a stick or when the button or pedals are (de)pressed. Each stick, pedal and button can trigger a different instrument number. The rbatonPercPad opcode allows the radio baton to activate notes belonging to up to 7 different instruments at the same time: the ones assigned to the two sticks, the ones assigned to the two pedals when switched down, the ones assigned to the two pedals when switched up, and the one assigned to the b15+ button. Since the input argument can be varied at k-rate, it is possible to have much more different instrument numbers activated at successive times. The duration of the notes is determined by current kDur value, expressed in seconds. This opcode allows to use the Radio Baton like a multi-facetted percussion pad (in theory, if the drummer could be precise enugh, the surface would be equivalent to a monster drum set of up to 128 X values * 128 Y values * 2 sticks = 32768 different drums, each one of them being velocity sensitive). See the argument descriptions above for more details. (N.B. It seems that my radio baton, which have a small antenna, is unable to output 100% reliable whack-strenght stick values. This happens especially with strong hits, some of which produce low p4 values, instead of high ones. I guess that this could be due to some firmware bug of the RB. I ignore wether other radio batons present the same drawback, my RB is release #55). rbatonXYZ tracks the positions of the two sticks independently, returning their spatial coordinates (normalized in the 0 to 1 range). Unfortunately, due to physical reasons, the tracking becomes less precise when the sticks go away from the baton antenna in the Z direction. When the sticks are near the antenna, the response is quite precise, even if a jitter could need lopass filtering the resulting signals, unless you deliberately want some special jittering effect. Actually the Radio Baton suffers (expecially in the Z axis) of a number of limitations even if they could deliberately be wanted as a peculiar expressive character. The Z axis has a very exponential response, retriving values that change fastly when moving the sticks near the antenna, but retriving values that change quite slowly when the sticks are far from the antenna. Also the X and Y axes have a different, non-linear response depending on how much the sticks are far from the antenna. When the sticks are near the antenna, the X-Y plane retrieves quite precise values. kpot1, kpot2, kpot3, kpot4, kfsw1, kfsw2, kbutton rbatonPot rbatonPot tracks the position of the pots, as well as the states of the two pedals and of the B15+ button. Notice that the B15+ button seems not to function when a mono jack is inserted in the B15- inlet (that of the foot-switch 1, the same thing happens with the B14- inlet and the B14+ button, that, anyway, cannot be used for performance). Curiously, I noticed that if you use a stereo jack, both the B15- pedal and the the B15+ button are active an functional at the same time. So I placed a stereo jack adapter to the mono jack of my pedals, in order to have the B14+ and B15+ buttons to function properly when the pedals are inserted. I don't know if this issue is only present on my Radio Baton (revision #55) or in all other Radio Batons. GEN51 This subroutine fills a table with a fully customized micro-tuning scale, in the manner of Csound opcodes cpstun, cpstuni and cpstmid. f# time size -51 numgrades interval basefreq basekey tuningRatio1 tuningRatio2 .... tuningRationN The first four parameters (i.e. p5, p6, p7 and p8) define the following generation directives: p5 (numgrades) - the number of grades of the micro-tuning scale p6 (interval) - the frequency range covered before repeating the grade ratios, for example 2 for one octave, 1.5 for a fifth etcetera p7 (basefreq) - the base frequency of the scale in cps p8 (basekey) - the integer index of the scale to which to assign basefreq unmodified p9...pN (tuningRatio1...etc.) - the tuning ratios of the scale For example, for a standard 12-grade scale with the base-frequency of 261 cps assigned to the key-number 60, the corresponding f-statement in the score to generate the table should be: ; numgrades basefreq tuning-ratios (eq.temp) ....... ; interval basekey f1 0 128 -51 12 2 261 60 1 1.059463 1.12246 1.18920 ..etc... After the gen has been processed, the table f1 is filled with 128 different frequency values. The 60th element is filled with the frequency value of 261, and all other elements (preceding and subsequents) of the table are filled according to the tuning ratios Another example with a 24-grade scale with a base frequency of 440 assigned to the key-number 48, and a repetition interval of 1.5: ; numgrades basefreq tuning-ratios ....... ; interval basekey f1 0 128 -2 24 1.5 440 48 1 1.01 1.02 1.03 ..etc... Table Morphing Opcodes kout tabmorph kindex, kweightpoint, ktabnum1, ktabnum2, ifn1, ifn2 [, ifn3, ifn4,…ifnN] kout tabmorphi kindex, kweightpoint, ktabnum1, ktabnum2, ifn1, ifn2 [, ifn3, ifn4,…ifnN] aout tabmorpha aindex, aweightpoint, atabnum1, atabnum2, ifn1, ifn2 [, ifn3, ifn4,…ifnN] aout tabmorphak aindex, kweightpoint, ktabnum1, ktabnum2, ifn1, ifn2 [, ifn3, ifn4,…ifnN] DESCRIPTION Allow morphing between a set of tables of the same size, by means of a weighted average between two currently selected tables. INTIALIZATION ifn1, ifn2 [, ifn3, ifn4,…ifnN] – function table numbers. This is a set of chosen tables the user want to use in the morphing. All tables must have the same length. Take into account that only a pair of tables can be chosen for the morphing at a time. Anyway, being it possible to use non-integer numbers for the ktabnum1 and ktabnum2 arguments (see below), in this case the pair of tables to be morphed result from the interpolation between adjacent consecutive tables of the set (see later for more information). PERFORMANCE kindex - main index index of the morphed resultant table. The range is 0 to table_length (not included). aindex - main index index of the morphed resultant table. The range is 0 to 1 (not included). Notice the range difference with respect to kindex. k(a)weightpoint - the weight of the influence of a pair of selected tables in the morphing. The range of this argument is 0 to 1. A zero makes it output the first table unaltered, a 1 makes it output the second table of the pair unaltered. All intermediate values between 0 and 1 determine the gradual morphing between the two tables of the pair. k(a)tabnum1, k(a)tabnum2 - the first and secon table chosen for the morphing. These numbers doesn’t express the table number directly, but the position of the table in the set sequence (starting from 0 to N-1). If this number is an integer, corresponding table will be chosen unaltered. If it contains fractional values, then an interpolation with the next adjacent table will result. The tabmorph family of opcodes is similar to the table family, but allows morphing between two tables chosen into a set of tables. Firstly the user has to provide a set of tables of equal length (ifn2 [, ifn3, ifn4,…ifnN]). Then she can choose a pair of table in the set in order to perform the morphing: ktabnum1 and ktabnum2 are filled with numbers (zero represents the first table in the set, 1 the second, 2 the third and so on). Then determine the morphing between the two chosen tables with the kweightpoint parameter. After all that the resulting table can be indexed with the k(a)index parameter like a normal table opcode. If the value of this parameter surpasses the length of tables (which must be the same for all tables), then it is wrapped around. tabmorph acts similarly to the table opcode, that is, without using interpolation. This means that it acts likewise the fractional part of the kindex argument is truncated. Anyway, fractional parts of ktabnum1 and ktabnum2 are significant, resulting in linear interpolation between the same element of two adjacent subsequent tables. tabmorphi acts similarly to the tablei opcode, that is, uses linear interpolation. For the rest is identical to tabmorph. tabmorpha is the audio-rate version of tabmorphi (it uses interpolation). All input arguments work at a-rate (except the table list ifn1, ifn2 [, ifn3, ifn4,…ifnN]). tabmorphak also works at a-rate, but kweightpoint, ktabnum1 and ktabnum2 are working at k-rate, making it more efficient than tabmorpha, since there are less calculations. Except the rate of these three arguments, is identical to tabmorpha. MIDI Slider opcodes with table output kflag slider8table ichan, ioutTable, ioffset, ictlnum1, imin1, imax1, init1, ifn1, .... , \ ictlnum8, imin8, imax8, init8, ifn8 kflag slider16table ichan, ioutTable, ioffset, ictlnum1, imin1, imax1, init1, ifn1, .... , \ ictlnum16, imin16, imax16, init16, ifn16 kflag slider32table ichan, ioutTable, ioffset, ictlnum1, imin1, imax1, init1, ifn1, .... , \ ictlnum32, imin32, imax32, init32, ifn32 kflag slider64table ichan, ioutTable, ioffset, ictlnum1, imin1, imax1, init1, ifn1, .... , \ ictlnum64, imin64, imax64, init64, ifn64 kflag slider8tablef ichan, ioutTable, ioffset, ictlnum1, imin1, imax1, init1, ifn1, icutoff1, .... , \ ictlnum8, imin8, imax8, init8, ifn8, icutoff8 kflag slider16tablef ichan, ioutTable, ioffset, ictlnum1, imin1, imax1, init1, ifn1, icutoff1, .... , \ ictlnum16, imin16, imax16, init16, ifn16, icutoff16 kflag slider32tablef ichan, ioutTable, ioffset, ictlnum1, imin1, imax1, init1, ifn1, icutoff1, .... , \ ictlnum32, imin32, imax32, init32, ifn32, icutoff32 kflag slider64tablef ichan, ioutTable, ioffset, ictlnum1, imin1, imax1, init1, ifn1, icutoff1, .... , \ ictlnum64, imin64, imax64, init64, ifn64, icutoff64 DESCRIPTION MIDI slider control banks. The output is tored into a table. .INTIALIZATION ichan - midi channel (1-16) ioutputTable – number of the table that will contain the output ioffset – output table offset. A zero means that the output of the first slider will affect the first table element. A 10 meanse that the output of the first slieder will affect the 11th table element. ictlnum1 ... ictlnum64 - midi control number ictlno_msb1 .... ictlno_msb32 - midi control number (most significant byte) ictlno_lsb1 .... ictlno_lsb32 - midi control number (less significant byte) imin1 ... imin64 - minimum values for each controller imax1 ... imax64 - maximum values for each controller init1 ... init64 - inital value for each controller ifn1 ... ifn64 - function table for conversion for each controller icutoff1 ... icutoff64 - low pass filter frequency cutoff for each controller PERFORMANCE sliderNtable and sliderNtablef are banks of MIDI controller, very similar to sliderN and sliderNf family of opcodes (see their manual for more information), The actual difference is that the output is not stored to k-rate variables, but to a table, denoted by the ioutTable argument. It is possible to define a starting index in order to use the same table for more than one slider bank (or other purposes). It is possible to use these opcdes together with FLslidBnk2Setk and FLslidBnk2, in this case you can synchronize the position of the MIDI values to the position of the FLTK valuator widgets of FLslidBnk2. Notice that you have to specify the same min/max values as well the linear/exponential responses in both sliderNtable(f) and FLslidBnk2. The exception is when using table-indexed response instead of a lin/exp response. In this case, in order to achieve a useful result, the table-indexed response and actual min/max values must be set only in FLslidBnk2, whereas, in sliderNtable(f), you have to set a linear response and a minimum of zero and a maximum of one in all sliders.