The OLPCsound Reference Manual

Version 5.08

Barry Vercoe

MIT Media Lab

et. al.


Table of Contents

Preface
Preface to the OLPCsound Manual
Getting Started with Csound
Tootorials
Toot 1
Toot 2
Toot 3
Toot 4
Toot 5
Toot 6
Toot 7
Toot 8
Toot 9
Toot 10
I. Overview
Using Csound
How Csound5 works
Amplitude values in Csound
Real-Time Audio
Optimizing Audio I/O Latency
Syntax of the Orchestra
Orchestra Header Statements
Instrument and Opcode Block Statements
Ordinary Statements
Constants and Variables
Variable Initialization
Expressions
Directories and Files
Nomenclature
Macros
Named Instruments
User Defined Opcodes (UDO)
The Standard Numeric Score
Preprocessing of Standard Scores
Carry
Tempo
Sort
Score Statements
Next-P and Previous-P Symbols
Ramping
Score Macros
Multiple File Score
Evaluation of Expressions
The Csound Command
Order of Precedence
Description of the command syntax
Csound command line
Command-line Flags
Csound Environment Variables
Unified File Format for Orchestras and Scores
Description
Example
Command Line Parameter File (.csoundrc)
Csound Links
II. Reference
Orchestra Opcodes and Operators
!= — Determines if one value is not equal to another.
#define — Defines a macro.
#include — Includes an external file for processing.
#undef — Un-defines a macro.
#ifdef — Conditional reading of code.
#ifndef — Conditional reading of code.
$NAME — Calls a defined macro.
% — Modulus operator.
&& — Logical AND operator.
> — Determines if one value is greater than another.
>= — Determines if one value is greater than or equal to another.
< — Determines if one value is less than another.
<= — Determines if one value is less than or equal to another.
* — Multiplication operator.
+ — Addition operator
- — Subtraction operator.
/ — Division operator.
= — Performs a simple assignment.
== — Compares two values for equality.
^ — “Power of” operator.
|| — Logical OR operator.
0dbfs — Sets the value of 0 decibels using full scale amplitude.
& — Bitwise AND operator.
| — Bitwise OR operator.
¬ — Bitwise NOT operator.
# — Bitwise NON EQUIVALENCE operator.
a — Converts a k-rate parameter to an a-rate value with interpolation.
abs — Returns an absolute value.
active — Returns the number of active instances of an instrument.
adsr — Calculates the classical ADSR envelope using linear segments.
adsyn — Output is an additive set of individually controlled sinusoids, using an oscillator bank.
adsynt — Performs additive synthesis with an arbitrary number of partials, not necessarily harmonic.
adsynt2 — Performs additive synthesis with an arbitrary number of partials -not necessarily harmonic- with interpolation.
aftouch — Get the current after-touch value for this channel.
alpass — Reverberates an input signal with a flat frequency response.
ampdb — Returns the amplitude equivalent of the decibel value x.
ampdbfs — Returns the amplitude equivalent of the decibel value x, which is relative to full scale amplitude.
ampmidi — Get the velocity of the current MIDI event.
areson — A notch filter whose transfer functions are the complements of the reson opcode.
aresonk — A notch filter whose transfer functions are the complements of the reson opcode.
atone — A hi-pass filter whose transfer functions are the complements of the tone opcode.
atonek — A hi-pass filter whose transfer functions are the complements of the tonek opcode.
atonex — Emulates a stack of filters using the atone opcode.
babo — A physical model reverberator.
balance — Adjust one audio signal according to the values of another.
bamboo — Semi-physical model of a bamboo sound.
barmodel — Creates a tone similar to a struck metal bar.
bbcutm — Generates breakbeat-style cut-ups of a mono audio stream.
bbcuts — Generates breakbeat-style cut-ups of a stereo audio stream.
betarand — Beta distribution random number generator (positive values only).
bexprnd — Exponential distribution random number generator.
bformenc — Codes a signal into the ambisonic B format
bformdec — Decodes an ambisonic B format signal
binit — PVS tracks to amplitude+frequency conversion.
biquad — A sweepable general purpose biquadratic digital filter.
biquada — A sweepable general purpose biquadratic digital filter with a-rate parameters.
birnd — Returns a random number in a bi-polar range.
bqrez — A second-order multi-mode filter.
butbp — Same as the butterbp opcode.
butbr — Same as the butterbr opcode.
buthp — Same as the butterhp opcode.
butlp — Same as the butterlp opcode.
butterbp — A band-pass Butterworth filter.
butterbr — A band-reject Butterworth filter.
butterhp — A high-pass Butterworth filter.
butterlp — A low-pass Butterworth filter.
buzz — Output is a set of harmonically related sine partials.
cabasa — Semi-physical model of a cabasa sound.
cauchy — Cauchy distribution random number generator.
ceil — Returns the smallest integer not less than x
cent — Calculates a factor to raise/lower a frequency by a given amount of cents.
cggoto — Conditionally transfer control on every pass.
chanctrl — Get the current value of a MIDI channel controller.
changed — k-rate signal change detector.
chani — Reads data from the software bus
chano — Send data to the outwards software bus
chebyshevpoly — Efficiently evaluates the sum of Chebyshev polynomials of arbitrary order.
chn — Declare a channel of the named software bus.
chnclear — Clears an audio output channel of the named software bus.
chnexport — Export a global variable as a channel of the bus.
chnget — Reads data from the software bus.
chnmix — Writes audio data to the named software bus, mixing to the previous output.
chnparams — Query parameters of a channel.
chnset — Writes data to the named software bus.
cigoto — Conditionally transfer control during the i-time pass.
ckgoto — Conditionally transfer control during the p-time passes.
clear — Zeroes a list of audio signals.
clfilt — Implements low-pass and high-pass filters of different styles.
clip — Clips a signal to a predefined limit.
clockoff — Stops one of a number of internal clocks.
clockon — Starts one of a number of internal clocks.
cngoto — Transfers control on every pass when a condition is not true.
comb — Reverberates an input signal with a “colored” frequency response.
compress — Compress, limit, expand, duck or gate an audio signal.
convle — Same as the convolve opcode.
convolve — Convolves a signal and an impulse response.
cos — Performs a cosine function.
cosh — Performs a hyperbolic cosine function.
cosinv — Performs a arccosine function.
cps2pch — Converts a pitch-class value into cycles-per-second (Hz) for equal divisions of the octave.
cpsmidi — Get the note number of the current MIDI event, expressed in cycles-per-second.
cpsmidib — Get the note number of the current MIDI event and modify it by the current pitch-bend value, express it in cycles-per-second.
cpsmidinn — Converts a Midi note number value to cycles-per-second.
cpsoct — Converts an octave-point-decimal value to cycles-per-second.
cpspch — Converts a pitch-class value to cycles-per-second.
cpstmid — Get a MIDI note number (allows customized micro-tuning scales).
cpstun — Returns micro-tuning values at k-rate.
cpstuni — Returns micro-tuning values at init-rate.
cpsxpch — Converts a pitch-class value into cycles-per-second (Hz) for equal divisions of any interval.
cpuprc — Control allocation of cpu resources on a per-instrument basis, to optimize realtime output.
cross2 — Cross synthesis using FFT's.
crunch — Semi-physical model of a crunch sound.
ctrl14 — Allows a floating-point 14-bit MIDI signal scaled with a minimum and a maximum range.
ctrl21 — Allows a floating-point 21-bit MIDI signal scaled with a minimum and a maximum range.
ctrl7 — Allows a floating-point 7-bit MIDI signal scaled with a minimum and a maximum range.
ctrlinit — Sets the initial values for a set of MIDI controllers.
cuserrnd — Continuous USER-defined-distribution RaNDom generator.
dam — A dynamic compressor/expander.
date — Returns the number seconds since 1 January 1970.
dates — Returns as a string the date and time specified.
db — Returns the amplitude equivalent for a given decibel amount.
dbamp — Returns the decibel equivalent of the raw amplitude x.
dbfsamp — Returns the decibel equivalent of the raw amplitude x, relative to full scale amplitude.
dcblock — A DC blocking filter.
dconv — A direct convolution opcode.
delay — Delays an input signal by some time interval.
delay1 — Delays an input signal by one sample.
delayk — Delays an input signal by some time interval.
delayr — Reads from an automatically established digital delay line.
delayw — Writes the audio signal to a digital delay line.
deltap — Taps a delay line at variable offset times.
deltap3 — Taps a delay line at variable offset times, uses cubic interpolation.
deltapi — Taps a delay line at variable offset times, uses interpolation.
deltapn — Taps a delay line at variable offset times.
deltapx — Read to or write from a delay line with interpolation.
deltapxw — Mixes the input signal to a delay line.
denorm — Mixes low level noise to a list of a-rate signals
diff — Modify a signal by differentiation.
diskgrain — Synchronous granular synthesis, using a soundfile as source.
diskin — Reads audio data from an external device or stream and can alter its pitch.
diskin2 — Reads audio data from a file, and can alter its pitch using one of several available interpolation types, as well as convert the sample rate to match the orchestra sr setting.
dispfft — Displays the Fourier Transform of an audio or control signal.
display — Displays the audio or control signals as an amplitude vs. time graph.
distort — Distort an audio signal via waveshaping and optional clipping.
distort1 — Modified hyperbolic tangent distortion.
divz — Safely divides two numbers.
downsamp — Modify a signal by down-sampling.
dripwater — Semi-physical model of a water drop.
dumpk — Periodically writes an orchestra control-signal value to an external file.
dumpk2 — Periodically writes two orchestra control-signal values to an external file.
dumpk3 — Periodically writes three orchestra control-signal values to an external file.
dumpk4 — Periodically writes four orchestra control-signal values to an external file.
duserrnd — Discrete USER-defined-distribution RaNDom generator.
else — Executes a block of code when an "if...then" condition is false.
elseif — Defines another "if...then" condition when a "if...then" condition is false.
endif — Closes a block of code that begins with an "if...then" statement.
endin — Ends the current instrument block.
endop — Marks the end of an user-defined opcode block.
envlpx — Applies an envelope consisting of 3 segments.
envlpxr — The envlpx opcode with a final release segment.
eqfil — Equalizer filter
event — Generates a score event from an instrument.
event_i — Generates a score event from an instrument.
exitnow — Exit csound as fast as possible, with no cleaning up.
exp — Returns e raised to the x-th power.
expcurve — This opcode implements a formula for generating a normalised exponential curve in range 0 - 1. It is based on the Max / MSP work of Eric Singer (c) 1994.
expon — Trace an exponential curve between specified points.
exprand — Exponential distribution random number generator (positive values only).
expseg — Trace a series of exponential segments between specified points.
expsega — An exponential segment generator operating at a-rate.
expsegr — Trace a series of exponential segments between specified points including a release segment.
ficlose — Closes a previously opened file.
filelen — Returns the length of a sound file.
filenchnls — Returns the number of channels in a sound file.
filepeak — Returns the peak absolute value of a sound file.
filesr — Returns the sample rate of a sound file.
filter2 — Performs filtering using a transposed form-II digital filter lattice with no time-varying control.
fin — Read signals from a file at a-rate.
fini — Read signals from a file at i-rate.
fink — Read signals from a file at k-rate.
fiopen — Opens a file in a specific mode.
flanger — A user controlled flanger.
flashtxt — Allows text to be displayed from instruments like sliders
flooper — Function-table-based crossfading looper.
flooper2 — Function-table-based crossfading looper.
floor — Returns the largest integer not greater than x
fmb3 — Uses FM synthesis to create a Hammond B3 organ sound.
fmbell — Uses FM synthesis to create a tublar bell sound.
fmmetal — Uses FM synthesis to create a “Heavy Metal” sound.
fmpercfl — Uses FM synthesis to create a percussive flute sound.
fmrhode — Uses FM synthesis to create a Fender Rhodes electric piano sound.
fmvoice — FM Singing Voice Synthesis
fmwurlie — Uses FM synthesis to create a Wurlitzer electric piano sound.
fof — Produces sinusoid bursts useful for formant and granular synthesis.
fof2 — Produces sinusoid bursts including k-rate incremental indexing with each successive burst.
fofilter — Formant filter.
fog — Audio output is a succession of grains derived from data in a stored function table
fold — Adds artificial foldover to an audio signal.
follow — Envelope follower unit generator.
follow2 — Another controllable envelope extractor.
foscil — A basic frequency modulated oscillator.
foscili — Basic frequency modulated oscillator with linear interpolation.
fout — Outputs a-rate signals to an arbitrary number of channels.
fouti — Outputs i-rate signals of an arbitrary number of channels to a specified file.
foutir — Outputs i-rate signals from an arbitrary number of channels to a specified file.
foutk — Outputs k-rate signals of an arbitrary number of channels to a specified file, in raw (headerless) format.
fprintks — Similar to printks but prints to a file.
fprints — Similar to prints but prints to a file.
frac — Returns the fractional part of a decimal number.
freeverb — Opcode version of Jezar's Freeverb
ftchnls — Returns the number of channels in a stored function table.
ftconv — Low latency multichannel convolution, using a function table as impulse response source.
ftfree — Deletes function table.
ftgen — Generate a score function table from within the orchestra.
ftgentmp — Generate a score function table from within the orchestra, which is deleted at the end of the note.
ftlen — Returns the size of a stored function table.
ftload — Load a set of previously-allocated tables from a file.
ftloadk — Load a set of previously-allocated tables from a file.
ftlptim — Returns the loop segment start-time of a stored function table number.
ftmorf — Morphs between multiple ftables as specified in a list.
ftsave — Save a set of previously-allocated tables to a file.
ftsavek — Save a set of previously-allocated tables to a file.
ftsr — Returns the sampling-rate of a stored function table.
gain — Adjusts the amplitude audio signal according to a root-mean-square value.
gainslider — An implementation of a logarithmic gain curve which is similar to the gainslider~ object from Cycling 74 Max / MSP.
gauss — Gaussian distribution random number generator.
gbuzz — Output is a set of harmonically related cosine partials.
getcfg — Return Csound settings.
gogobel — Audio output is a tone related to the striking of a cow bell or similar.
goto — Transfer control on every pass.
grain — Generates granular synthesis textures.
grain2 — Easy-to-use granular synthesis texture generator.
grain3 — Generate granular synthesis textures with more user control.
granule — A more complex granular synthesis texture generator.
guiro — Semi-physical model of a guiro sound.
harmon — Analyze an audio input and generate harmonizing voices in synchrony.
harmon2 — Analyze an audio input and generate harmonizing voices in synchrony with formants preserved.
hilbert — A Hilbert transformer.
hrtfer — Creates 3D audio for two speakers.
hrtfmove — Generates dynamic 3d binaural audio for headphones using magnitude interpolation and phase truncation.
hrtfmove2 — Generates dynamic 3d binaural audio for headphones using a Woodworth based spherical head model with improved low frequency phase accuracy.
hrtfstat — Generates static 3d binaural audio for headphones using a Woodworth based spherical head model with improved low frequency phase accuracy.
hsboscil — An oscillator which takes tonality and brightness as arguments.
hvs1 — Allows one-dimensional Hyper Vectorial Synthesis (HVS) controlled by externally-updated k-variables.
hvs2 — Allows two-dimensional Hyper Vectorial Synthesis (HVS) controlled by externally-updated k-variables.
hvs3 — Allows three-dimensional Hyper Vectorial Synthesis (HVS) controlled by externally-updated k-variables.
i — Returns an init-type equivalent of a k-rate argument.
if — Branches conditionally at initialization or during performance time.
igoto — Transfer control during the i-time pass.
ihold — Creates a held note.
imagecreate — Create an empty image of a given size.
imagefree — Frees memory allocated for a previously loaded or created image.
imagegetpixel — Return the RGB pixel values of a previously opened or created image.
imageload — Load an image.
imagesave — Save a previously created image.
imagesetpixel — Set the RGB value of a pixel inside a previously opened or created image.
imagesize — Return the width and height of a previously opened or created image.
in — Reads mono audio data from an external device or stream.
inch — Reads from a numbered channel in an external audio signal or stream.
init — Puts the value of the i-time expression into a k- or a-rate variable.
initc14 — Initializes the controllers used to create a 14-bit MIDI value.
initc21 — Initializes the controllers used to create a 21-bit MIDI value.
initc7 — Initializes the controller used to create a 7-bit MIDI value.
inrg — Allow input from a range of adjacent audio channels from the audio input device
ins — Reads stereo audio data from an external device or stream.
insremot — An opcode which can be used to implement a remote orchestra. This opcode will send note events from a source machine to one destination.
insglobal — An opcode which can be used to implement a remote orchestra. This opcode will send note events from a source machine to many destinations.
instr — Starts an instrument block.
int — Extracts an integer from a decimal number.
integ — Modify a signal by integration.
interp — Converts a control signal to an audio signal using linear interpolation.
invalue — Reads a k-rate signal from a user-defined channel.
inz — Reads multi-channel audio samples into a ZAK array from an external device or stream.
jacktransport — Start/stop jack_transport and can optionally relocate the playback head.
jitter — Generates a segmented line whose segments are randomly generated.
jitter2 — Generates a segmented line with user-controllable random segments.
jspline — A jitter-spline generator.
k — Converts a i-rate parameter to an k-rate value.
kgoto — Transfer control during the p-time passes.
kr — Sets the control rate.
ksmps — Sets the number of samples in a control period.
ktableseg — Deprecated.
lfo — A low frequency oscillator of various shapes.
limit — Sets the lower and upper limits of the value it processes.
line — Trace a straight line between specified points.
linen — Applies a straight line rise and decay pattern to an input amp signal.
linenr — The linen opcode extended with a final release segment.
lineto — Generate glissandos starting from a control signal.
linrand — Linear distribution random number generator (positive values only).
linseg — Trace a series of line segments between specified points.
linsegr — Trace a series of line segments between specified points including a release segment.
locsend — Distributes the audio signals of a previous locsig opcode.
locsig — Takes and input signal and distributes between 2 or 4 channels.
log — Returns a natural log.
log10 — Returns a base 10 log.
logbtwo — Performs a logarithmic base two calculation.
logcurve — This opcode implements a formula for generating a normalised logarithmic curve in range 0 - 1. It is based on the Max / MSP work of Eric Singer (c) 1994.
loop_ge — Looping constructions.
loop_gt — Looping constructions.
loop_le — Looping constructions.
loop_lt — Looping constructions.
loopseg — Generate control signal consisting of linear segments delimited by two or more specified points.
loopsegp — Control signals based on linear segments.
lorenz — Implements the Lorenz system of equations.
loscil — Read sampled sound from a table.
loscil3 — Read sampled sound from a table using cubic interpolation.
loscilx — Loop oscillator.
lowpass2 — A resonant lowpass filter.
lowres — Another resonant lowpass filter.
lowresx — Simulates layers of serially connected resonant lowpass filters.
lpf18 — A 3-pole sweepable resonant lowpass filter.
lpfreson — Resynthesises a signal from the data passed internally by a previous lpread, applying formant shifting.
lphasor — Generates a table index for sample playback
lpinterp — Computes a new set of poles from the interpolation between two analysis.
lposcil — Read sampled sound from a table with optional looping and high precision.
lposcil3 — Read sampled sound from a table with high precision and cubic interpolation.
lposcila — Read sampled sound from a table with optional looping and high precision.
lposcilsa — Read stereo sampled sound from a table with optional looping and high precision.
lposcilsa2 — Read stereo sampled sound from a table with optional looping and high precision.
lpread — Reads a control file of time-ordered information frames.
lpreson — Resynthesises a signal from the data passed internally by a previous lpread.
lpshold — Generate control signal consisting of held segments.
lpsholdp — Control signals based on held segments.
lpslot — Selects the slot to be use by further lp opcodes.
mac — Multiplies and accumulates a- and k-rate signals.
maca — Multiply and accumulate a-rate signals only.
madsr — Calculates the classical ADSR envelope using the linsegr mechanism.
mandel — Mandelbrot set
mandol — An emulation of a mandolin.
marimba — Physical model related to the striking of a wooden block.
massign — Assigns a MIDI channel number to a Csound instrument.
max — Produces a signal that is the maximum of any number of input signals.
maxabs — Produces a signal that is the maximum of the absolute values of any number of input signals.
maxabsaccum — Accumulates the maximum of the absolute values of audio signals.
maxaccum — Accumulates the maximum value of audio signals.
maxalloc — Limits the number of allocations of an instrument.
max_k — Local maximum (or minimum) value of an incoming asig signal
mclock — Sends a MIDI CLOCK message.
mdelay — A MIDI delay opcode.
metro — Trigger Metronome
midic14 — Allows a floating-point 14-bit MIDI signal scaled with a minimum and a maximum range.
midic21 — Allows a floating-point 21-bit MIDI signal scaled with a minimum and a maximum range.
midic7 — Allows a floating-point 7-bit MIDI signal scaled with a minimum and a maximum range.
midichannelaftertouch — Gets a MIDI channel's aftertouch value.
midichn — Returns the MIDI channel number from which the note was activated.
midicontrolchange — Gets a MIDI control change value.
midictrl — Get the current value (0-127) of a specified MIDI controller.
mididefault — Changes values, depending on MIDI activation.
midiin — Returns a generic MIDI message received by the MIDI IN port.
midinoteoff — Gets a MIDI noteoff value.
midinoteoncps — Gets a MIDI note number as a cycles-per-second frequency.
midinoteonkey — Gets a MIDI note number value.
midinoteonoct — Gets a MIDI note number value as octave-point-decimal value.
midinoteonpch — Gets a MIDI note number as a pitch-class value.
midion — Generates MIDI note messages at k-rate.
midion2 — Sends noteon and noteoff messages to the MIDI OUT port.
midiout — Sends a generic MIDI message to the MIDI OUT port.
midipitchbend — Gets a MIDI pitchbend value.
midipolyaftertouch — Gets a MIDI polyphonic aftertouch value.
midiprogramchange — Gets a MIDI program change value.
miditempo — Returns the current tempo at k-rate, of either the MIDI file (if available) or the score
midremot — An opcode which can be used to implement a remote midi orchestra. This opcode will send midi events from a source machine to one destination.
midglobal — An opcode which can be used to implement a remote midi orchestra. This opcode will broadcast the midi events to all the machines involved in the remote concert.
min — Produces a signal that is the minimum of any number of input signals.
minabs — Produces a signal that is the minimum of the absolute values of any number of input signals.
minabsaccum — Accumulates the minimum of the absolute values of audio signals.
minaccum — Accumulates the minimum value of audio signals.
mirror — Reflects the signal that exceeds the low and high thresholds.
MixerSetLevel — Sets the level of a send to a buss.
MixerGetLevel — Gets the level of a send to a buss.
MixerSend — Mixes an arate signal into a channel of a buss.
MixerReceive — Receives an arate signal from a channel of a buss.
MixerClear — Resets all channels of a buss to 0.
mode — A filter that simulates a mass-spring-damper system
monitor — Returns the audio spout frame.
moog — An emulation of a mini-Moog synthesizer.
moogladder