The Canonical Csound Reference Manual

Frames Version

Version 5.08

Barry Vercoe

MIT Media Lab

Other Contributors

John ffitch

Jean Piché

Peter Nix

Richard Boulanger

Rasmus Ekman

David Boothe

Kevin Conder

Steven Yi

Michael Gogins

Andrés Cabrera

François Pinot

Anthony Kozar


Table of Contents

Preface
Preface to the Csound Manual
Acknowledgements
History of the Canonical Csound Reference Manual
Copyright Notice
Getting Started with Csound
What's new in Csound 5.08
I. Overview
Introduction
Recent Developments
Features of Csound 5
Features of CsoundAC
The Csound Command
Order of Precedence
Description of the command syntax
Csound command line
Command-line Flags (by Category)
Csound Environment Variables
Unified File Format for Orchestras and Scores
Description
Example
Command Line Parameter File (.csoundrc)
Score File Preprocessing
The Extract Feature
Independent Pre-Processing with Scsort
Using Csound
How Csound5 works
Amplitude values in Csound
Real-Time Audio
Realtime I/O on Linux
Windows
Mac
Optimizing Audio I/O Latency
Configuring
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
Front Ends
CsoundAC
CsoundVST
TclCsound
The Tcl interpreter: cstclsh
Cswish: the windowing shell
A Csound server
A Scripting Environment
TclCsound as a language wrapper
TclCsound Command Reference
Building Csound
Csound Links
II. Opcodes Overview
Signal Generators
Additive Synthesis/Resynthesis
Basic Oscillators
Dynamic Spectrum Oscillators
FM Synthesis
Granular Synthesis
Hyper Vectorial Synthesis
Linear and Exponential Generators
Envelope Generators
Models and Emulations
Phasors
Random (Noise) Generators
Sample Playback
Soundfonts
Scanned Synthesis
Table Access
Wave Terrain Synthesis
Waveguide Physical Modeling
Signal Input and Output
File Input and Output
Signal Input
Signal Output
Software Bus
Printing and Display
Sound File Queries
Signal Modifiers
Amplitude Modifiers and Dynamic processing
Convolution and Morphing
Delay
Panning and Spatialization
Reverberation
Sample Level Operators
Signal Limiters
Special Effects
Standard Filters
Specialized Filters
Waveguides
Waveshaping and Phase Distortion
Instrument Control
Clock Control
Conditional Values
Duration Control Statements
FLTK Widgets and GUI controllers
FLTK Containers
FLTK Valuators
Other FLTK Widgets
Modifying FLTK Widget Appearance
General FLTK Widget-related Opcodes
Instrument Invocation
Program Flow Control
Real-time Performance Control
Initialization and Reinitialization
Sensing and Control
Stacks
Sub-instrument Control
Time Reading
Function Table Control
Table Queries
Read/Write Operations
Table Reading with Dynamic Selection
Mathematical Operations
Amplitude Converters
Arithmetic and Logic Operations
Comparators and Accumulators
Mathematical Functions
Opcode Equivalents of Functions
Random Functions
Trigonometric Functions
Pitch Converters
Functions
Tuning Opcodes
Real-time MIDI Support
Virtual MIDI Keyboard
MIDI input
MIDI Message Output
Generic Input and Output
Converters
Event Extenders
Note-on/Note-off Output
MIDI/Score Interoperability opcodes
System Realtime Messages
Slider Banks
Spectral Processing
Short-time Fourier Transform (STFT) Resynthesis
Linear Predictive Coding (LPC) Resynthesis
Non-standard Spectral Processing
Tools for Real-time Spectral Processing (pvs opcodes)
ATS Spectral Processing
Loris Opcodes
Strings
String Manipulation Opcodes
String Conversion Opcodes
Vectorial Opcodes
Tables of vectors operators
Operations Between a Vectorial and a Scalar Signal
Operations Between two Vectorial Signals
Vectorial Envelope Generators
Limiting and wrapping of vectorial control signals
Vectorial Control-rate Delay Paths
Vectorial Random Signal Generators
Zak Patch System
Plugin Hosting
DSSI and LADSPA for Csound
VST for Csound
OSC and Network
OSC
Network
Remote Opcodes
Mixer Opcodes
Python Opcodes
Introduction
Orchestra Syntax
Image processing opcodes
Miscellaneous opcodes
III. 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.
abetarand — Deprecated.
abexprnd — Deprecated.
abs — Returns an absolute value.
acauchy — Deprecated.
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.
aexprand — Deprecated.
aftouch — Get the current after-touch value for this channel.
agauss — Deprecated.
agogobel — Deprecated.
alinrand — Deprecated.
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.
apcauchy — Deprecated.
apoisson — Deprecated.
apow — Deprecated.
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.
atrirand — Deprecated.
ATSadd — uses the data from an ATS analysis file to perform additive synthesis.
ATSaddnz — uses the data from an ATS analysis file to perform noise resynthesis.
ATSbufread — reads data from and ATS data file and stores it in an internal data table of frequency, amplitude pairs.
ATScross — perform cross synthesis from ATS analysis files.
ATSinfo — reads data out of the header of an ATS file.
ATSinterpread — allows a user to determine the frequency envelope of any ATSbufread.
ATSread — reads data from an ATS file.
ATSreadnz — reads data from an ATS file.
ATSpartialtap — returns a frequency, amplitude pair from an ATSbufread opcode.
ATSsinnoi — uses the data from an ATS analysis file to perform resynthesis.
aunirand — Deprecated.
aweibull — Deprecated.
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 stuck 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.
button — Sense on-screen controls.
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.
checkbox — Sense on-screen controls.
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.
clock — Deprecated.
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.
control — Configurable slider controls for realtime user input.
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.
dssiactivate — Activates or deactivates a DSSI or LADSPA plugin.
dssiaudio — Processes audio using a LADSPA or DSSI plugin.
dssictls — Send control information to a LADSPA or DSSI plugin.
dssiinit — Loads a DSSI or LADSPA plugin.
dssilist — Lists all available DSSI and LADSPA plugins.
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
FLbox — A FLTK widget that displays text inside of a box.
FLbutBank — A FLTK widget opcode that creates a bank of buttons.
FLbutton — A FLTK widget opcode that creates a button.
FLcloseButton — A FLTK widget opcode that creates a button that will close the panel window it is a part of.
FLcolor — A FLTK opcode that sets the primary colors.
FLcolor2 — A FLTK opcode that sets the secondary (selection) color.
FLcount — A FLTK widget opcode that creates a counter.
FLexecButton — A FLTK widget opcode that creates a button that executes a command.
FLgetsnap — Retrieves a previously stored FLTK snapshot.
FLgroup — A FLTK container opcode that groups child widgets.
FLgroupEnd — Marks the end of a group of FLTK child widgets.
FLgroupEnd — Marks the end of a group of FLTK child widgets.
FLhide — Hides the target FLTK widget.
FLhvsBox — Displays a box with a grid useful for visualizing two-dimensional Hyper Vectorial Synthesis.
FLhvsBoxSetValue — Sets the cursor position of a previously-declared FLhvsBox widget.
FLjoy — A FLTK opcode that acts like a joystick.
FLkeyIn — Reports keys pressed (on alphanumeric keyboard) when an FLTK panel has focus.
FLknob — A FLTK widget opcode that creates a knob.
FLlabel — A FLTK opcode that modifies the appearance of a text label.
FLloadsnap — Loads all snapshots into the memory bank of the current orchestra.
FLmouse — Returns the mouse position and the state of the three mouse buttons.
flooper — Function-table-based crossfading looper.
flooper2 — Function-table-based crossfading looper.
floor — Returns the largest integer not greater than x
FLpack — Provides the functionality of compressing and aligning FLTK widgets.
FLpackEnd — Marks the end of a group of compressed or aligned FLTK widgets.
FLpack_end — Marks the end of a group of compressed or aligned FLTK widgets.
FLpanel — Creates a window that contains FLTK widgets.
FLpanelEnd — Marks the end of a group of FLTK widgets contained inside of a window (panel).
FLpanel_end — Marks the end of a group of FLTK widgets contained inside of a window (panel).
FLprintk — A FLTK opcode that prints a k-rate value at specified intervals.
FLprintk2 — A FLTK opcode that prints a new value every time a control-rate variable changes.
FLroller — A FLTK widget that creates a transversal knob.
FLrun — Starts the FLTK widget thread.
FLsavesnap — Saves all snapshots currently created into a file.
FLscroll — A FLTK opcode that adds scroll bars to an area.
FLscrollEnd — A FLTK opcode that marks the end of an area with scrollbars.
FLscroll_end — A FLTK opcode that marks the end of an area with scrollbars.
FLsetAlign — Sets the text alignment of a label of a FLTK widget.
FLsetBox — Sets the appearance of a box surrounding a FLTK widget.
FLsetColor — Sets the primary color of a FLTK widget.
FLsetColor2 — Sets the secondary (or selection) color of a FLTK widget.
FLsetFont — Sets the font type of a FLTK widget.
FLsetPosition — Sets the position of a FLTK widget.
FLsetSize — Resizes a FLTK widget.
FLsetsnap — Stores the current status of all FLTK valuators into a snapshot location.
FLsetSnapGroup — Determines the snapshot group for FL valuators.
FLsetText — Sets the label of a FLTK widget.
FLsetTextColor — Sets the color of the text label of a FLTK widget.
FLsetTextSize — Sets the size of the text label of a FLTK widget.
FLsetTextType — Sets some font attributes of the text label of a FLTK widget.
FLsetVal_i — Sets the value of a FLTK valuator to a number provided by the user.
FLsetVal — Sets the value of a FLTK valuator at control-rate.
FLshow — Restores the visibility of a previously hidden FLTK widget.
FLslidBnk — A FLTK widget containing a bank of horizontal sliders.
FLslidBnk2 — A FLTK widget containing a bank of horizontal sliders.
FLslidBnkGetHandle — gets the handle of last slider bank created.
FLslidBnkSet — modify the values of a slider bank.
FLslidBnkSetk — modify the values of a slider bank.
FLslidBnk2Set — modify the values of a slider bank.
FLslidBnk2Setk — modify the values of a slider bank.
FLslider — Puts a slider into the corresponding FLTK container.
FLtabs — Creates a tabbed FLTK interface.
FLtabsEnd — Marks the end of a tabbed FLTK interface.
FLtabs_end — Marks the end of a tabbed FLTK interface.
FLtext — A FLTK widget opcode that creates a textbox.
FLupdate — Same as the FLrun opcode.
fluidAllOut — Collects all audio from all Fluidsynth engines in a performance
fluidCCi — Sends a MIDI controller data message to fluid.
fluidCCk — Sends a MIDI controller data message to fluid.