*csound*
Csound Help File	~

This is the Csound Manual formatted as a Vim Help File by Luis Jure, based on
the Alternative Csound Reference Manual edited by Kevin Conder.

It's available at:
http://www.eumus.edu.uy/docentes/jure/csound/vim/

Please report errors in the formatting or suggest improvements to it sending
an e-mail to the Csound mailing list, or to this address:

lj@eumus.edu.uy

Installation	~

Uncompress the file and copy it to $VIMRUNTIME/doc, where all the other help
files should be located.

Then, as root run the following command from within vim:

:helptags $VIMRUNTIME/doc

Basic Usage	~

":he csound" will jump to the top of this document, once there you can navigate
in the usual ways.
":he oscil" or any other opcode name jump directly to the entry for that
opcode.
When the cursor is on an opcode, typing "K" in normal mode also jump directly
to the entry for that opcode

For further details, see ":he help"


Many thanks to Kevin Conder for maintaining the ACRM and allowing me to use it
for this project. The original text follows, with all proper credits.

------------------------------------------------------------------------------
The Alternative Csound Reference Manual	~

Barry Vercoe
MIT Media Lab

Other Contributors

Edited by

John ffitch
Jean Piché
Peter Nix
Richard Boulanger
Rasmus Ekman
David Boothe
Kevin Conder

4.23-1 Edition

Table of Contents	~

|prefacetop| Preface
|prefacepreface| Preface to the Csound Manual
|prefacecopy| Copyright Notice
|prefaceacknowledgements| Acknowledgements
|prefacename| Why is this called the Alternative Csound Reference Manual?
|prefacescope| What is the scope of the Alternative Csound Reference Manual?
|prefacecsoundav| Where is the documentation for the CsoundAV project?

|partoverview| Overview
|introtop| Introduction
|introget| Where to Get Public Csound and the Csound Manual
|introinstall| How to Install Csound
|introinstalllinux| Linux
|introinstallmac| Macintosh
|introinstallmsdos| MS-DOS and Windows 95/NT
|introinstallwindow| Windows 95/98/2000
|introinstallother| Other Platforms
|introlist| The Csound Mailing List
|introlistbugs| Bug Reports
|commandtop| The Csound Command
|commandorder| Order of Precedence
|commanddesc| Description
|commandflags| Command-line Flags
|commandunifile| Unified File Format for Orchestras and Scores
|commandpreproc| Score File Preprocessing
|commandpreextract| The Extract Feature
|commandpreindie| Independent Pre-Processing with Scsort
|orchtop| Syntax of the Orchestra
|orchdirfiles| Directories and Files
|orchnomen| Nomenclature
|orchstatemnt| Orchestra Statement Types
|orchkvar| Constants and Variables
|orchexpress| Expressions
|orchheader| Orchestra Header Statements
|orchiblock| Instrument Block Statements
|orchvarinit| Variable Initialization
|controltop| Instrument Control
|controlclockctl| Clock Control
|controlconditional| Conditional Values
|controldurctl| Duration Control Statements
|controlfltkintro| Introduction to FLTK Widgets and GUI controllers
|controlfltkcontainers| FLTK Containers
|controlfltkvaluators| FLTK Valuators
|controlfltkother| Other FLTK Widgets
|controlfltkappearance| Modifying FLTK Widget Appearance
|controlfltkgeneral| General FLTK Widget-related Opcodes
|controlfltksliderbank| FLTK Slider Bank
|controlinvocat| Instrument Invocation
|controlmacros| Macros
|controlpgmctl| Program Flow Control
|controlrealtime| Real-time Performance Control
|controlreinitn| Reinitialization
|controlsensing| Sensing and Control
|controlsubinstrument| Sub-instrument Control
|controltimeread| Time Reading
|tabletop| Function Table Control
|tablequeries| Table Queries
|tablereadwrit| Read/Write Operations
|tableselect| Table Selection
|mathtop| Mathematical Operations
|mathamp| Amplitude Converters
|mathartlogic| Arithmetic and Logic Operations
|mathmatfunc| Mathematical Functions
|mathopeqfunc| Opcode Equivalents of Functions
|mathrndfunc| Random Functions
|mathtrig| Trigonometric Functions
|miditop| MIDI Support
|midicontrol| Controller Input
|midiconvert| Converters
|midiextender| Event Extenders
|midigeneric| Generic Input and Output
|midionoff| Note-on/Note-off
|midioutput| MIDI Message Output
|midirealtime| Real-time Messages
|midislidrbk| Slider Banks
|pitchtop| Pitch Converters
|pitchfuncs| Functions
|pitchtuning| Tuning Opcodes
|siggentop| Signal Generators
|siggenadditive| Additive Synthesis/Resynthesis
|siggenbasic| Basic Oscillators
|siggendynamic| Dynamic Spectrum Oscillators
|siggenfmsynth| FM Synthesis
|siggengranular| Granular Synthesis
|siggenlineexp| Linear and Exponential Generators
|siggenlpcresyn| Linear Predictive Coding (LPC) Resynthesis
|siggenmodels| Models and Emulations
|siggenphasors| Phasors
|siggennoise| Random (Noise) Generators
|siggensample| Sample Playback
|siggenscantop| Scanned Synthesis
|siggenstft| Short-time Fourier Transform (STFT) Resynthesis
|siggentableacc| Table Access
|siggenwaveterr| Wave Terrain Synthesis
|siggenwavguide| Waveguide Physical Modeling
|sigiotop| Signal Input and Output
|sigiofileio| File Input and Output
|sigioinput| Input
|sigiooutput| Output
|sigiopdisplay| Printing and Display
|sigioqueries| Sound File Queries
|sigmodtop| Signal Modifiers
|sigmodampmod| Amplitude Modifiers
|sigmodconmorph| Convolution and Morphing
|sigmoddelay| Delay
|sigmodenvelope| Envelope Modifiers
|sigmodpanspatl| Panning and Spatialization
|sigmodreverbtn| Reverberation
|sigmodsample| Sample Level Operators
|sigmodsiglimit| Signal Limiters
|sigmodspeciale| Special Effects
|sigmodspeciali| Specialized Filters
|sigmodstandard| Standard Filters
|sigmodwavguide| Waveguides
|spectraltop| Spectral Processing
|spectralnonstand| Non-standard Spectral Processing
|spectralrealtime| Tools for Real-time Spectral Processing
|zaktop| Zak Patch System
|scoretop| The Standard Numeric Score
|scorepreproc| Preprocessing of Standard Scores
|scorecarry| Carry
|scoretempo| Tempo
|scoresort| Sort
|scorenb| N.B.
|scorenextp| Next-P and Previous-P Symbols
|scoreramping| Ramping
|scoremacros| Score Macros
|mult| Multiple File Score
|scoreeval| Evaluation of Expressions
|scorestatements| Score Statements
|scoresinegen| Sine/Cosine Generators
|scoreseggen| Line/Exponential Segment Generators
|scorefilegen| File Access GEN Routines
|scorenumgen| Numeric Value Access GEN Routines
|scorewingen| Window Function GEN Routines
|scorerandgen| Random Function GEN Routines
|scorewavegen| Waveshaping GEN Routines
|scoreampgen| Amplitude Scaling GEN Routines
|scoremixgen| Mixing GEN Routines

|partreference| Reference
|opcodestop| Orchestra Opcodes and Operators
|notequal| != -- Determines if one value is not equal to another.
|define| #define -- Defines a macro.
|include| #include -- Includes an external file for processing.
|undef| #undef -- Un-defines a macro.
|dollar| $NAME -- Calls a defined macro.
|modulus| % -- Modulus operator.
|opand| && -- Logical AND operator.
|greaterthan| > -- Determines if one value is greater than another.
|greaterequal| >= -- Determines if one value is greater than or equal to
	another.
|lessthan| < -- Determines if one value is less than another.
|lessequal| <= -- Determines if one value is less than or equal to another.
|multiplies| * -- Multiplication operator.
|adds| + -- Addition operator
|subtracts| - -- Subtraction operator.
|divides| / -- Division operator.
|assign| = -- Performs a simple assignment.
|equals| == -- Compares two values for equality.
|raises| ^ -- "Power of" operator.
|opor| || -- Logical OR operator.
|zerodbfs| 0dbfs -- Sets the value of 0 decibels using full scale amplitude.
|opa| a -- Converts a k-rate parameter to an a-rate value with interpolation.
|abetarand| abetarand -- Deprecated.
|abexprnd| abexprnd -- Deprecated.
|abs| abs -- Returns an absolute value.
|acauchy| acauchy -- Deprecated.
|active| active -- Returns the number of active instances of an instrument.
|adsr| adsr -- Calculates the classical ADSR envelope using linear segments.
|adsyn| adsyn -- Output is an additive set of individually controlled
	sinusoids, using an oscillator bank.
|adsynt| adsynt -- Performs additive synthesis with an arbitrary number of
	partials, not necessarily harmonic.
|aexprand| aexprand -- Deprecated.
|aftouch| aftouch -- Get the current after-touch value for this channel.
|agauss| agauss -- Deprecated.
|agogobel| agogobel -- Deprecated.
|alinrand| alinrand -- Deprecated.
|alpass| alpass -- Reverberates an input signal with a flat frequency
	response.
|ampdb| ampdb -- Returns the amplitude equivalent of the decibel value x.
|ampdbfs| ampdbfs -- Returns the amplitude equivalent of the decibel value x,
	which is relative to full scale amplitude.
|ampmidi| ampmidi -- Get the velocity of the current MIDI event.
|apcauchy| apcauchy -- Deprecated.
|apoisson| apoisson -- Deprecated.
|apow| apow -- Deprecated.
|areson| areson -- A notch filter whose transfer functions are the complements
	of the reson opcode.
|aresonk| aresonk -- A notch filter whose transfer functions are the
	complements of the reson opcode.
|atone| atone -- A notch filter whose transfer functions are the complements
	of the tone opcode.
|atonek| atonek -- A notch filter whose transfer functions are the complements
	of the tone opcode.
|atonex| atonex -- Emulates a stack of filters using the atone opcode.
|atrirand| atrirand -- Deprecated.
|aunirand| aunirand -- Deprecated.
|aweibull| aweibull -- Deprecated.
|babo| babo -- A physical model reverberator.
|balance| balance -- Adjust one audio signal according to the values of
	another.
|bamboo| bamboo -- Semi-physical model of a bamboo sound.
|bbcutm| bbcutm -- Generates breakbeat-style cut-ups of a mono audio stream.
|bbcuts| bbcuts -- Generates breakbeat-style cut-ups of a stereo audio stream.
|betarand| betarand -- Beta distribution random number generator (positive
	values only).
|bexprnd| bexprnd -- Exponential distribution random number generator.
|biquad| biquad -- A sweepable general purpose biquadratic digital filter.
|biquada| biquada -- A sweepable general purpose biquadratic digital filter
	with a-rate parameters.
|birnd| birnd -- Returns a random number in a bi-polar range.
|bqrez| bqrez -- A second-order multi-mode filter.
|butbp| butbp -- Same as the butterbp opcode.
|butbr| butbr -- Same as the butterbr opcode.
|buthp| buthp -- Same as the butterhp opcode.
|butlp| butlp -- Same as the butterlp opcode.
|butterbp| butterbp -- A band-pass Butterworth filter.
|butterbr| butterbr -- A band-reject Butterworth filter.
|butterhp| butterhp -- A high-pass Butterworth filter.
|butterlp| butterlp -- A low-pass Butterworth filter.
|button| button -- Sense on-screen controls.
|buzz| buzz -- Output is a set of harmonically related sine partials.
|cabasa| cabasa -- Semi-physical model of a cabasa sound.
|cauchy| cauchy -- Cauchy distribution random number generator.
|cent| cent -- Calculates a factor to raise/lower a frequency by a given
	amount of cents.
|cggoto| cggoto -- Conditionally transfer control on every pass.
|chanctrl| chanctrl -- Get the current value of a MIDI channel controller.
|checkbox| checkbox -- Sense on-screen controls.
|cigoto| cigoto -- Conditionally transfer control during the i-time pass.
|ckgoto| ckgoto -- Conditionally transfer control during the p-time passes.
|clear| clear -- Zeroes a list of audio signals.
|clfilt| clfilt -- Implements low-pass and high-pass filters of different
	styles.
|clip| clip -- Clips a signal to a predefined limit.
|clock| clock -- Deprecated.
|clockoff| clockoff -- Stops one of a number of internal clocks.
|clockon| clockon -- Starts one of a number of internal clocks.
|cngoto| cngoto -- Transfers control on every pass when a condition is not
	true.
|comb| comb -- Reverberates an input signal with a "colored" frequency
	response.
|control| control -- Configurable slider controls for realtime user input.
|convle| convle -- Same as the convolve opcode.
|convolve| convolve -- Convolves a signal and an impulse response.
|cos| cos -- Performs a cosine function.
|cosh| cosh -- Performs a hyperbolic cosine function.
|cosinv| cosinv -- Performs a arccosine function.
|cps2pch| cps2pch -- Converts a pitch-class value into cycles-per-second for
	equal divisions of the octave.
|cpsmidi| cpsmidi -- Get the note number of the current MIDI event, expressed
	in cycles-per-second.
|cpsmidib| 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.
|cpsoct| cpsoct -- Converts an octave-point-decimal value to
	cycles-per-second.
|cpspch| cpspch -- Converts a pitch-class value to cycles-per-second.
|cpstmid| cpstmid -- Get a MIDI note number (allows customized micro-tuning
	scales).
|cpstun| cpstun -- Returns micro-tuning values at k-rate.
|cpstuni| cpstuni -- Returns micro-tuning values at init-rate.
|cpsxpch| cpsxpch -- Converts a pitch-class value into cycles-per-second (Hz)
	for equal divisions of any interval.
|cpuprc| cpuprc -- Control allocation of cpu resources on a per-instrument
	basis, to optimize realtime output.
|cross2| cross2 -- Cross synthesis using FFT's.
|crunch| crunch -- Semi-physical model of a crunch sound.
|ctrl14| ctrl14 -- Allows a floating-point 14-bit MIDI signal scaled with a
	minimum and a maximum range.
|ctrl21| ctrl21 -- Allows a floating-point 21-bit MIDI signal scaled with a
	minimum and a maximum range.
|ctrl7| ctrl7 -- Allows a floating-point 7-bit MIDI signal scaled with a
	minimum and a maximum range.
|ctrlinit| ctrlinit -- Sets the initial values for a set of MIDI controllers.
|cuserrnd| cuserrnd -- Continuous USER-defined-distribution RaNDom generator.
|dam| dam -- A dynamic compressor/expander.
|db| db -- Returns the amplitude equivalent for a given decibel amount.
|dbamp| dbamp -- Returns the decibel equivalent of the raw amplitude x.
|dbfsamp| dbfsamp -- Returns the decibel equivalent of the raw amplitude x,
	relative to full scale amplitude.
|dcblock| dcblock -- A DC blocking filter.
|dconv| dconv -- A direct convolution opcode.
|delay| delay -- Delays an input signal by some time interval.
|delay1| delay1 -- Delays an input signal by one sample.
|delayr| delayr -- Reads from an automatically established digital delay line.
|delayw| delayw -- Writes the audio signal to a digital delay line.
|deltap| deltap -- Taps a delay line at variable offset times.
|deltap3| deltap3 -- Taps a delay line at variable offset times, uses cubic
	interpolation.
|deltapi| deltapi -- Taps a delay line at variable offset times, uses
	interpolation.
|deltapn| deltapn -- Taps a delay line at variable offset times.
|deltapx| deltapx -- Read to or write from a delay line with interpolation.
|deltapxw| deltapxw -- Mixes the input signal to a delay line.
|diff| diff -- Modify a signal by differentiation.
|diskin| diskin -- Reads audio data from an external device or stream and can
	alter its pitch.
|dispfft| dispfft -- Displays the Fourier Transform of an audio or control
	signal.
|display| display -- Displays the audio or control signals as an amplitude vs.
	time graph.
|distort1| distort1 -- Modified hyperbolic tangent distortion.
|divz| divz -- Safely divides two numbers.
|downsamp| downsamp -- Modify a signal by down-sampling.
|dripwater| dripwater -- Semi-physical model of a water drop.
|dumpk| dumpk -- Periodically writes an orchestra control-signal value to an
	external file.
|dumpk2| dumpk2 -- Periodically writes two orchestra control-signal values to
	an external file.
|dumpk3| dumpk3 -- Periodically writes three orchestra control-signal values
	to an external file.
|dumpk4| dumpk4 -- Periodically writes four orchestra control-signal values to
	an external file.
|duserrnd| duserrnd -- Discrete USER-defined-distribution RaNDom generator.
|else| else -- Executes a block of code when an "if...then" condition is
	false.
|elseif| elseif -- Defines another "if...then" condition when a "if...then"
	condition is false.
|endif| endif -- Closes a block of code that begins with an "if...then"
	statement.
|endin| endin -- Ends the current instrument block.
|endop| endop -- Marks the end of an user-defined opcode block.
|envlpx| envlpx -- Applies an envelope consisting of 3 segments.
|envlpxr| envlpxr -- The envlpx opcode with a final release segment.
|event| event -- Generates a score event from an instrument.
|exp| exp -- Returns e raised to the x-th power.
|expon| expon -- Trace an exponential curve between specified points.
|exprand| exprand -- Exponential distribution random number generator
	(positive values only).
|expseg| expseg -- Trace a series of exponential segments between specified
	points.
|expsega| expsega -- An exponential segment generator operating at a-rate.
|expsegr| expsegr -- Trace a series of exponential segments between specified
	points including a release segment.
|filelen| filelen -- Returns the length of a sound file.
|filenchnls| filenchnls -- Returns the number of channels in a sound file.
|filepeak| filepeak -- Returns the peak absolute value of a sound file.
|filesr| filesr -- Returns the sample rate of a sound file.
|filter2| filter2 -- Performs filtering using a transposed form-II digital
	filter lattice with no time-varying control.
|fin| fin -- Read signals from a file at a-rate.
|fini| fini -- Read signals from a file at i-rate.
|fink| fink -- Read signals from a file at k-rate.
|fiopen| fiopen -- Opens a file in a specific mode.
|flanger| flanger -- A user controlled flanger.
|flashtxt| flashtxt -- Allows text to be displayed from instruments like
	sliders
|flbox| FLbox -- A FLTK widget that displays text inside of a box.
|flbutbank| FLbutBank -- A FLTK widget opcode that creates a bank of buttons.
|flbutton| FLbutton -- A FLTK widget opcode that creates a button.
|flcolor| FLcolor -- A FLTK opcode that sets the primary colors.
|flcolor2| FLcolor2 -- A FLTK opcode that sets the secondary (selection)
	color.
|flcount| FLcount -- A FLTK widget opcode that creates a counter.
|flgetsnap| FLgetsnap -- Retrieves a previously stored FLTK snapshot.
|flgroup| FLgroup -- A FLTK container opcode that groups child widgets.
|flgroupend| FLgroupEnd -- Marks the end of a group of FLTK child widgets.
|flhide| FLhide -- Hides the target FLTK widget.
|fljoy| FLjoy -- A FLTK opcode that acts like a joystick.
|flkeyb| FLkeyb -- Experimental, no documentation exists. May be deprecated in
	future versions.
|flknob| FLknob -- A FLTK widget opcode that creates a knob.
|fllabel| FLlabel -- A FLTK opcode that modifies the appearance of a text
	label.
|flloadsnap| FLloadsnap -- Loads all snapshots into the memory bank of the
	current orchestra.
|flpack| FLpack -- Provides the functionality of compressing and aligning FLTK
	widgets.
|flpackend| FLpackEnd -- Marks the end of a group of compressed or aligned
	FLTK widgets.
|flpanel| FLpanel -- Creates a window that contains FLTK widgets.
|flpanelend| FLpanelEnd -- Marks the end of a group of FLTK widgets contained
	inside of a window (panel).
|flprintk| FLprintk -- A FLTK opcode that prints a k-rate value at specified
	intervals.
|flprintk2| FLprintk2 -- A FLTK opcode that prints a new value every time a
	control-rate variable changes.
|flroller| FLroller -- A FLTK widget that creates a transversal knob.
|flrun| FLrun -- Starts the FLTK widget thread.
|flsavesnap| FLsavesnap -- Saves all snapshots currently created into a file.
|flscroll| FLscroll -- A FLTK opcode that adds scroll bars to an area.
|flscrollend| FLscrollEnd -- A FLTK opcode that marks the end of an area with
	scrollbars.
|flsetalign| FLsetAlign -- Sets the text alignment of a label of a FLTK
	widget.
|flsetbox| FLsetBox -- Sets the appearance of a box surrounding a FLTK widget.
|flsetcolor| FLsetColor -- Sets the primary color of a FLTK widget.
|flsetcolor2| FLsetColor2 -- Sets the secondary (or selection) color of a FLTK
	widget.
|flsetfont| FLsetFont -- Sets the font type of a FLTK widget.
|flsetposition| FLsetPosition -- Sets the position of a FLTK widget.
|flsetsize| FLsetSize -- Resizes a FLTK widget.
|flsetsnap| FLsetsnap -- Stores the current status of all FLTK valuators into
	a snapshot location.
|flsettext| FLsetText -- Sets the label of a FLTK widget.
|flsettextcolor| FLsetTextColor -- Sets the color of the text label of a FLTK
	widget.
|flsettextsize| FLsetTextSize -- Sets the size of the text label of a FLTK
	widget.
|flsettexttype| FLsetTextType -- Sets some font attributes of the text label
	of a FLTK widget.
|flsetvali| FLsetVal_i -- Sets the value of a FLTK valuator to a number
	provided by the user.
|flsetval| FLsetVal -- Sets the value of a FLTK valuator at control-rate.
|flshow| FLshow -- Restores the visibility of a previously hidden FLTK widget.
|flslidbnk| FLslidBnk -- A FLTK widget containing a bank of horizontal
	sliders.
|flslider| FLslider -- Puts a slider into the corresponding FLTK container.
|fltabs| FLtabs -- Creates a tabbed FLTK interface.
|fltabsend| FLtabsEnd -- Marks the end of a tabbed FLTK interface.
|fltext| FLtext -- A FLTK widget opcode that creates a textbox.
|flupdate| FLupdate -- Same as the FLrun opcode.
|flvalue| FLvalue -- Shows the current value of a FLTK valuator.
|fmb3| fmb3 -- Uses FM synthesis to create a Hammond B3 organ sound.
|fmbell| fmbell -- Uses FM synthesis to create a tublar bell sound.
|fmmetal| fmmetal -- Uses FM synthesis to create a "Heavy Metal" sound.
|fmpercfl| fmpercfl -- Uses FM synthesis to create a percussive flute sound.
|fmrhode| fmrhode -- Uses FM synthesis to create a Fender Rhodes electric
	piano sound.
|fmvoice| fmvoice -- FM Singing Voice Synthesis
|fmwurlie| fmwurlie -- Uses FM synthesis to create a Wurlitzer electric piano
	sound.
|fof| fof -- Produces sinusoid bursts useful for formant and granular
	synthesis.
|fof2| fof2 -- Produces sinusoid bursts including k-rate incremental indexing
	with each successive burst.
|fog| fog -- Audio output is a succession of grains derived from data in a
	stored function table
|fold| fold -- Adds artificial foldover to an audio signal.
|follow| follow -- Envelope follower unit generator.
|follow2| follow2 -- Another controllable envelope extractor.
|foscil| foscil -- A basic frequency modulated oscillator.
|foscili| foscili -- Basic frequency modulated oscillator with linear
	interpolation.
|fout| fout -- Outputs a-rate signals to an arbitrary number of channels.
|fouti| fouti -- Outputs i-rate signals of an arbitrary number of channels to
	a specified file.
|foutir| foutir -- Outputs i-rate signals from an arbitrary number of channels
	to a specified file.
|foutk| foutk -- Outputs k-rate signals of an arbitrary number of channels to
	a specified file.
|fprintks| fprintks -- Similar to printks but prints to a file.
|fprints| fprints -- Similar to prints but prints to a file.
|frac| frac -- Returns the fractional part of a decimal number.
|ftchnls| ftchnls -- Returns the number of channels in a stored function
	table.
|ftgen| ftgen -- Generate a score function table from within the orchestra.
|ftlen| ftlen -- Returns the size of a stored function table.
|ftload| ftload -- Load a set of previously-allocated tables from a file.
|ftloadk| ftloadk -- Load a set of previously-allocated tables from a file.
|ftlptim| ftlptim -- Returns the loop segment start-time of a stored function
	table number.
|ftmorf| ftmorf -- Morphs between multiple ftables as specified in a list.
|ftsave| ftsave -- Save a set of previously-allocated tables to a file.
|ftsavek| ftsavek -- Save a set of previously-allocated tables to a file.
|ftsr| ftsr -- Returns the sampling-rate of a stored function table.
|gain| gain -- Adjusts the amplitude audio signal according to a
	root-mean-square value.
|gauss| gauss -- Gaussian distribution random number generator.
|gbuzz| gbuzz -- Output is a set of harmonically related cosine partials.
|gogobel| gogobel -- Audio output is a tone related to the striking of a cow
	bell or similar.
|goto| goto -- Transfer control on every pass.
|grain| grain -- Generates granular synthesis textures.
|grain2| grain2 -- Easy-to-use granular synthesis texture generator.
|grain3| grain3 -- Generate granular synthesis textures with more user
	control.
|granule| granule -- A more complex granular synthesis texture generator.
|guiro| guiro -- Semi-physical model of a guiro sound.
|harmon| harmon -- Analyze an audio input and generate harmonizing voices in
	synchrony.
|hilbert| hilbert -- A Hilbert transformer.
|hrtfer| hrtfer -- Creates 3D audio for two speakers.
|hsboscil| hsboscil -- An oscillator which takes tonality and brightness as
	arguments.
|opi| i -- Returns an init-type equivalent of a k-rate argument.
|ibetarand| ibetarand -- Deprecated.
|ibexprnd| ibexprnd -- Deprecated.
|icauchy| icauchy -- Deprecated.
|ictrl14| ictrl14 -- Deprecated.
|ictrl21| ictrl21 -- Deprecated.
|ictrl7| ictrl7 -- Deprecated.
|iexprand| iexprand -- Deprecated.
|if| if -- Branches conditionally at initialization or during performance
	time.
|igauss| igauss -- Deprecated.
|igoto| igoto -- Transfer control during the i-time pass.
|ihold| ihold -- Creates a held note.
|ilinrand| ilinrand -- Deprecated.
|imidic14| imidic14 -- Deprecated.
|imidic21| imidic21 -- Deprecated.
|imidic7| imidic7 -- Deprecated.
|in| in -- Reads mono audio data from an external device or stream.
|in32| in32 -- Reads a 32-channel audio signal from an external device or
	stream.
|inch| inch -- Reads from a numbered channel in an external audio signal or
	stream.
|inh| inh -- Reads six-channel audio data from an external device or stream.
|init| init -- Puts the value of the i-time expression into a k- or a-rate
	variable.
|initc14| initc14 -- Initializes the controllers used to create a 14-bit MIDI
	value.
|initc21| initc21 -- Initializes the controllers used to create a 21-bit MIDI
	value.
|initc7| initc7 -- Initializes the controller used to create a 7-bit MIDI
	value.
|ink| ink -- Passes k-rate values into a sub-instrument.
|ino| ino -- Reads eight-channel audio data from an external device or stream.
|inq| inq -- Reads quad audio data from an external device or stream.
|ins| ins -- Reads stereo audio data from an external device or stream.
|instimek| instimek -- Deprecated.
|instimes| instimes -- Deprecated.
|instr| instr -- Starts an instrument block.
|int| int -- Extracts an integer from a decimal number.
|integ| integ -- Modify a signal by integration.
|interp| interp -- Converts a control signal to an audio signal using linear
	interpolation.
|invalue| invalue -- Reads a k-rate signal from a user-defined channel.
|inx| inx -- Reads a 16-channel audio signal from an external device or
	stream.
|inz| inz -- Reads multi-channel audio samples into a ZAK array from an
	external device or stream.
|ioff| ioff -- Deprecated.
|ion| ion -- Deprecated.
|iondur| iondur -- Deprecated.
|iondur2| iondur2 -- Deprecated.
|ioutat| ioutat -- Deprecated.
|ioutc| ioutc -- Deprecated.
|ioutc14| ioutc14 -- Deprecated.
|ioutpat| ioutpat -- Deprecated.
|ioutpb| ioutpb -- Deprecated.
|ioutpc| ioutpc -- Deprecated.
|ipcauchy| ipcauchy -- Deprecated.
|ipoisson| ipoisson -- Deprecated.
|ipow| ipow -- Deprecated.
|is16b14| is16b14 -- Deprecated.
|is32b14| is32b14 -- Deprecated.
|islider16| islider16 -- Deprecated.
|islider32| islider32 -- Deprecated.
|islider64| islider64 -- Deprecated.
|islider8| islider8 -- Deprecated.
|itablecopy| itablecopy -- Deprecated.
|itablegpw| itablegpw -- Deprecated.
|itablemix| itablemix -- Deprecated.
|itablew| itablew -- Deprecated.
|itrirand| itrirand -- Deprecated.
|iunirand| iunirand -- Deprecated.
|iweibull| iweibull -- Deprecated.
|jitter| jitter -- Generates a segmented line whose segments are randomly
	generated.
|jitter2| jitter2 -- Generates a segmented line with user-controllable random
	segments.
|jspline| jspline -- A jitter-spline generator.
|kbetarand| kbetarand -- Deprecated.
|kbexprnd| kbexprnd -- Deprecated.
|kcauchy| kcauchy -- Deprecated.
|kdump| kdump -- Deprecated.
|kdump2| kdump2 -- Deprecated.
|kdump3| kdump3 -- Deprecated.
|kdump4| kdump4 -- Deprecated.
|kexprand| kexprand -- Deprecated.
|kfilter2| kfilter2 -- Deprecated.
|kgauss| kgauss -- Deprecated.
|kgoto| kgoto -- Transfer control during the p-time passes.
|klinrand| klinrand -- Deprecated.
|kon| kon -- Deprecated.
|koutat| koutat -- Deprecated.
|koutc| koutc -- Deprecated.
|koutc14| koutc14 -- Deprecated.
|koutpat| koutpat -- Deprecated.
|koutpb| koutpb -- Deprecated.
|koutpc| koutpc -- Deprecated.
|kpcauchy| kpcauchy -- Deprecated.
|kpoisson| kpoisson -- Deprecated.
|kpow| kpow -- Deprecated.
|kr| kr -- Sets the control rate.
|kread| kread -- Deprecated.
|kread2| kread2 -- Deprecated.
|kread3| kread3 -- Deprecated.
|kread4| kread4 -- Deprecated.
|ksmps| ksmps -- Sets the number of samples in a control period.
|ktableseg| ktableseg -- Same as the tableseg opcode.
|ktrirand| ktrirand -- Deprecated.
|kunirand| kunirand -- Deprecated.
|kweibull| kweibull -- Deprecated.
|lfo| lfo -- A low frequency oscillator of various shapes.
|limit| limit -- Sets the lower and upper limits of the value it processes.
|line| line -- Trace a straight line between specified points.
|linen| linen -- Applies a straight line rise and decay pattern to an input
	amp signal.
|linenr| linenr -- The linen opcode extended with a final release segment.
|lineto| lineto -- Generate glissandos starting from a control signal.
|linrand| linrand -- Linear distribution random number generator (positive
	values only).
|linseg| linseg -- Trace a series of line segments between specified points.
|linsegr| linsegr -- Trace a series of line segments between specified points
	including a release segment.
|locsend| locsend -- Distributes the audio signals of a previous locsig
	opcode.
|locsig| locsig -- Takes and input signal and distributes between 2 or 4
	channels.
|log| log -- Returns a natural log.
|log10| log10 -- Returns a base 10 log.
|logbtwo| logbtwo -- Performs a logarithmic base two calculation.
|loopseg| loopseg -- Generate control signal consisting of linear segments
	delimited by two or more specified points.
|lorenz| lorenz -- Implements the Lorenz system of equations.
|loscil| loscil -- Read sampled sound from a table.
|loscil3| loscil3 -- Read sampled sound from a table using cubic
	interpolation.
|lowpass2| lowpass2 -- A resonant lowpass filter.
|lowres| lowres -- Another resonant lowpass filter.
|lowresx| lowresx -- Simulates layers of serially connected resonant lowpass
	filters.
|lpf18| lpf18 -- A 3-pole sweepable resonant lowpass filter.
|lpfreson| lpfreson -- Modifies the spectrum of an audio signal with
	time-varying filter coefficients from a control file and frequncy ratio.
|lphasor| lphasor -- Generates a table index for sample playback
|lpinterp| lpinterp -- Computes a new set of poles from the interpolation
	between two analysis.
|lposcil| lposcil -- Read sampled sound from a table with optional looping and
	high precision.
|lposcil3| lposcil3 -- Read sampled sound from a table with high precision and
	cubic interpolation.
|lpread| lpread -- Reads a control file of time-ordered information frames.
|lpreson| lpreson -- Modifies the spectrum of an audio signal with
	time-varying filter coefficients from a control file.
|lpshold| lpshold -- Generate control signal consisting of held segments.
|lpslot| lpslot -- Selects the slot to be use by further lp opcodes.
|mac| mac -- Multiplies and accumulates a- and k-rate signals.
|maca| maca -- Multiply and accumulate a-rate signals only.
|madsr| madsr -- Calculates the classical ADSR envelope using the linsegr
	mechanism.
|mandol| mandol -- An emulation of a mandolin.
|marimba| marimba -- Physical model related to the striking of a wooden block.
|massign| massign -- Assigns a MIDI channel number to a Csound instrument.
|maxalloc| maxalloc -- Limits the number of allocations of an instrument.
|mclock| mclock -- Sends a MIDI CLOCK message.
|mdelay| mdelay -- A MIDI delay opcode.
|midic14| midic14 -- Allows a floating-point 14-bit MIDI signal scaled with a
	minimum and a maximum range.
|midic21| midic21 -- Allows a floating-point 21-bit MIDI signal scaled with a
	minimum and a maximum range.
|midic7| midic7 -- Allows a floating-point 7-bit MIDI signal scaled with a
	minimum and a maximum range.
|midichannelaftertouch| midichannelaftertouch -- Gets a MIDI channel's
	aftertouch value.
|midichn| midichn -- Returns the MIDI channel number from which the note was
	activated.
|midicontrolchange| midicontrolchange -- Gets a MIDI control change value.
|midictrl| midictrl -- Get the current value (0-127) of a specified MIDI
	controller.
|mididefault| mididefault -- Changes values, depending on MIDI activation.
|midiin| midiin -- Returns a generic MIDI message received by the MIDI IN
	port.
|midinoteoff| midinoteoff -- Gets a MIDI noteoff value.
|midinoteoncps| midinoteoncps -- Gets a MIDI note number as a
	cycles-per-second frequency.
|midinoteonkey| midinoteonkey -- Gets a MIDI note number value.
|midinoteonoct| midinoteonoct -- Gets a MIDI note number value as
	octave-point-decimal value.
|midinoteonpch| midinoteonpch -- Gets a MIDI note number as a pitch-class
	value.
|midion| midion -- Plays MIDI notes.
|midion2| midion2 -- Sends noteon and noteoff messages to the MIDI OUT port.
|midiout| midiout -- Sends a generic MIDI message to the MIDI OUT port.
|midipitchbend| midipitchbend -- Gets a MIDI pitchbend value.
|midipolyaftertouch| midipolyaftertouch -- Gets a MIDI polyphonic aftertouch
	value.
|midiprogramchange| midiprogramchange -- Gets a MIDI program change value.
|mirror| mirror -- Reflects the signal that exceeds the low and high
	thresholds.
|moog| moog -- An emulation of a mini-Moog synthesizer.
|moogvcf| moogvcf -- A digital emulation of the Moog diode ladder filter
	configuration.
|moscil| moscil -- Sends a stream of the MIDI notes.
|mpulse| mpulse -- Generates a set of impulses.
|mrtmsg| mrtmsg -- Send system real-time messages to the MIDI OUT port.
|multitap| multitap -- Multitap delay line implementation.
|mute| mute -- Mutes/unmutes new instances of a given instrument.
|mxadsr| mxadsr -- Calculates the classical ADSR envelope using the expsegr
	mechanism.
|nchnls| nchnls -- Sets the number of channels of audio output.
|nestedap| nestedap -- Three different nested all-pass filters.
|nlfilt| nlfilt -- A filter with a non-linear effect.
|noise| noise -- A white noise generator with an IIR lowpass filter.
|noteoff| noteoff -- Send a noteoff message to the MIDI OUT port.
|noteon| noteon -- Send a noteon message to the MIDI OUT port.
|noteondur| noteondur -- Sends a noteon and a noteoff MIDI message both with
	the same channel, number and velocity.
|noteondur2| noteondur2 -- Sends a noteon and a noteoff MIDI message both with
	the same channel, number and velocity.
|notnum| notnum -- Get a note number from a MIDI event.
|nreverb| nreverb -- A reverberator consisting of 6 parallel comb-lowpass
	filters.
|nrpn| nrpn -- Sends a Non-Registered Parameter Number to the MIDI OUT port.
|nsamp| nsamp -- Returns the number of samples loaded into a stored function
	table number.
|nstrnum| nstrnum -- Returns the number of a named instrument.
|ntrpol| ntrpol -- Calculates the weighted mean value of two input signals.
|octave| octave -- Calculates a factor to raise/lower a frequency by a given
	amount of octaves.
|octcps| octcps -- Converts a cycles-per-second value to octave-point-decimal.
|octmidi| octmidi -- Get the note number, in octave-point-decimal units, of
	the current MIDI event.
|octmidib| octmidib -- Get the note number of the current MIDI event and
	modify it by the current pitch-bend value, express it in octave-point-decimal.
|octpch| octpch -- Converts a pitch-class value to octave-point-decimal.
|opcode| opcode -- Defines the start of user-defined opcode block.
|oscbnk| oscbnk -- Mixes the output of any number of oscillators.
|oscil| oscil -- A simple oscillator.
|oscil1| oscil1 -- Accesses table values by incremental sampling.
|oscil1i| oscil1i -- Accesses table values by incremental sampling with linear
	interpolation.
|oscil3| oscil3 -- A simple oscillator with cubic interpolation.
|oscili| oscili -- A simple oscillator with linear interpolation.
|oscilikt| oscilikt -- A linearly interpolated oscillator that allows changing
	the table number at k-rate.
|osciliktp| osciliktp -- A linearly interpolated oscillator that allows allows
	phase modulation.
|oscilikts| oscilikts -- A linearly interpolated oscillator with sync status
	that allows changing the table number at k-rate.
|osciln| osciln -- Accesses table values at a user-defined frequency.
|oscils| oscils -- A simple, fast sine oscillator
|oscilx| oscilx -- Same as the osciln opcode.
|out| out -- Writes mono audio data to an external device or stream.
|out32| out32 -- Writes 32-channel audio data to an external device or stream.
|outc| outc -- Writes audio data with an arbitrary number of channels to an
	external device or stream.
|outch| outch -- Writes multi-channel audio data, with user-controllable
	channels, to an external device or stream.
|outh| outh -- Writes 6-channel audio data to an external device or stream.
|outiat| outiat -- Sends MIDI aftertouch messages at i-rate.
|outic| outic -- Sends MIDI controller output at i-rate.
|outic14| outic14 -- Sends 14-bit MIDI controller output at i-rate.
|outipat| outipat -- Sends polyphonic MIDI aftertouch messages at i-rate.
|outipb| outipb -- Sends MIDI pitch-bend messages at i-rate.
|outipc| outipc -- Sends MIDI program change messages at i-rate
|outk| outk -- Passes k-rate values out of a sub-instrument.
|outkat| outkat -- Sends MIDI aftertouch messages at k-rate.
|outkc| outkc -- Sends MIDI controller messages at k-rate.
|outkc14| outkc14 -- Sends 14-bit MIDI controller output at k-rate.
|outkpat| outkpat -- Sends polyphonic MIDI aftertouch messages at k-rate.
|outkpb| outkpb -- Sends MIDI pitch-bend messages at k-rate.
|outkpc| outkpc -- Sends MIDI program change messages at k-rate.
|outo| outo -- Writes 8-channel audio data to an external device or stream.
|outq| outq -- Writes 4-channel audio data to an external device or stream.
|outq1| outq1 -- Writes samples to quad channel 1 of an external device or
	stream.
|outq2| outq2 -- Writes samples to quad channel 2 of an external device or
	stream.
|outq3| outq3 -- Writes samples to quad channel 3 of an external device or
	stream.
|outq4| outq4 -- Writes samples to quad channel 4 of an external device or
	stream.
|outs| outs -- Writes stereo audio data to an external device or stream.
|outs1| outs1 -- Writes samples to stereo channel 1 of an external device or
	stream.
|outs2| outs2 -- Writes samples to stereo channel 2 of an external device or
	stream.
|outvalue| outvalue -- Sends a k-rate signal to a user-defined channel.
|outx| outx -- Writes 16-channel audio data to an external device or stream.
|outz| outz -- Writes multi-channel audio data from a ZAK array to an external
	device or stream.
|p| p -- Show the value in a given p-field.
|pan| pan -- Distribute an audio signal amongst four channels.
|pareq| pareq -- Implementation of Zoelzer's parametric equalizer filters.
|pcauchy| pcauchy -- Cauchy distribution random number generator (positive
	values only).
|pchbend| pchbend -- Get the current pitch-bend value for this channel.
|pchmidi| pchmidi -- Get the note number of the current MIDI event, expressed
	in pitch-class units.
|pchmidib| pchmidib -- Get the note number of the current MIDI event and
	modify it by the current pitch-bend value, express it in pitch-class units.
|pchoct| pchoct -- Converts an octave-point-decimal value to pitch-class.
|peak| peak -- Maintains the output equal to the highest absolute value
	received.
|peakk| peakk -- Deprecated.
|pgmassign| pgmassign -- Assigns an instrument number to a specified MIDI
	program.
|phaser1| phaser1 -- First-order allpass filters arranged in a series.
|phaser2| phaser2 -- Second-order allpass filters arranged in a series.
|phasor| phasor -- Produce a normalized moving phase value.
|phasorbnk| phasorbnk -- Produce an arbitrary number of normalized moving
	phase values.
|pinkish| pinkish -- Generates approximate pink noise.
|pitch| pitch -- Tracks the pitch of a signal.
|pitchamdf| pitchamdf -- Follows the pitch of a signal based on the AMDF
	method.
|planet| planet -- Simulates a planet orbiting in a binary star system.
|pluck| pluck -- Produces a naturally decaying plucked string or drum sound.
|poisson| poisson -- Poisson distribution random number generator (positive
	values only).
|polyaft| polyaft -- Returns the polyphonic after-touch pressure of the
	selected note number.
|port| port -- Applies portamento to a step-valued control signal.
|portk| portk -- Applies portamento to a step-valued control signal.
|poscil| poscil -- High precision oscillator.
|poscil3| poscil3 -- High precision oscillator with cubic interpolation.
|pow| pow -- Computes one argument to the power of another argument.
|powoftwo| powoftwo -- Performs a power-of-two calculation.
|prealloc| prealloc -- Creates space for instruments but does not run them.
|print| print -- Displays the values init, control, or audio signals.
|printk| printk -- Prints one k-rate value at specified intervals.
|printk2| printk2 -- Prints a new value every time a control variable changes.
|printks| printks -- Prints at k-rate using a printf() style syntax.
|prints| prints -- Prints at init-time using a printf() style syntax.
|product| product -- Multiplies any number of a-rate signals.
|pset| pset -- Defines and initializes numeric arrays at orchestra load time.
|pvadd| pvadd -- Reads from a pvoc file and uses the data to perform additive
	synthesis.
|pvbufread| pvbufread -- Reads from a phase vocoder analysis file and makes
	the retrieved data available.
|pvcross| pvcross -- Applies the amplitudes from one phase vocoder analysis
	file to the data from a second file.
|pvinterp| pvinterp -- Interpolates between the amplitudes and frequencies of
	two phase vocoder analysis files.
|pvoc| pvoc -- Implements signal reconstruction using an fft-based phase
	vocoder.
|pvread| pvread -- Reads from a phase vocoder analysis file and returns the
	frequency and amplitude from a single analysis channel or bin.
|pvsadsyn| pvsadsyn -- Resynthesize using a fast oscillator-bank.
|pvsanal| pvsanal -- Generate an fsig from a mono audio source ain, using
	phase vocoder overlap-add analysis.
|pvscross| pvscross -- Performs cross-synthesis between two source fsigs.
|pvsfread| pvsfread -- Read a selected channel from a PVOC-EX analysis file.
|pvsftr| pvsftr -- Reads amplitude and/or frequency data from function tables.
|pvsftw| pvsftw -- Writes amplitude and/or frequency data to function tables.
|pvsinfo| pvsinfo -- Get information from a PVOC-EX formatted source.
|pvsmaska| pvsmaska -- Modify amplitudes using a function table, with dynamic
	scaling.
|pvsynth| pvsynth -- Resynthesise using a FFT overlap-add.
|rand| rand -- Generates a controlled random number series.
|randh| randh -- Generates random numbers and holds them for a period of time.
|randi| randi -- Generates a controlled random number series with
	interpolation between each new number.
|random| random -- Generates is a controlled pseudo-random number series
	between min and max values.
|randomh| randomh -- Generates random numbers with a user-defined limit and
	holds them for a period of time.
|randomi| randomi -- Generates a user-controlled random number series with
	interpolation between each new number.
|readclock| readclock -- Reads the value of an internal clock.
|readk| readk -- Periodically reads an orchestra control-signal value from an
	external file.
|readk2| readk2 -- Periodically reads two orchestra control-signal values from
	an external file.
|readk3| readk3 -- Periodically reads three orchestra control-signal values
	from an external file.
|readk4| readk4 -- Periodically reads four orchestra control-signal values
	from an external file.
|reinit| reinit -- Suspends a performance while a special initialization pass
	is executed.
|release| release -- Indicates whether a note is in its "release" stage.
|repluck| repluck -- Physical model of the plucked string.
|reson| reson -- A second-order resonant filter.
|resonk| resonk -- A second-order resonant filter.
|resonr| resonr -- A bandpass filter with variable frequency response.
|resonx| resonx -- Emulates a stack of filters using the reson opcode.
|resony| resony -- A bank of second-order bandpass filters, connected in
	parallel.
|resonz| resonz -- A bandpass filter with variable frequency response.
|reverb| reverb -- Reverberates an input signal with a "natural room"
	frequency response.
|reverb2| reverb2 -- Same as the nreverb opcode.
|rezzy| rezzy -- A resonant low-pass filter.
|rigoto| rigoto -- Transfers control during a reinit pass.
|rireturn| rireturn -- Terminates a reinit pass.
|rms| rms -- Determines the root-mean-square amplitude of an audio signal.
|rnd| rnd -- Returns a random number in a unipolar range.
|rnd31| rnd31 -- 31-bit bipolar random opcodes with controllable distribution.
|rspline| rspline -- Generate random spline curves.
|rtclock| rtclock -- Read the real time clock from the operating system.
|s16b14| s16b14 -- Creates a bank of 16 different 14-bit MIDI control message
	numbers.
|s32b14| s32b14 -- Creates a bank of 32 different 14-bit MIDI control message
	numbers.
|samphold| samphold -- Performs a sample-and-hold operation on its input.
|sandpaper| sandpaper -- Semi-physical model of a sandpaper sound.
|scanhammer| scanhammer -- Copies from one table to another with a gain
	control.
|scans| scans -- Generate audio output using scanned synthesis.
|scantable| scantable -- A simpler scanned synthesis implementation.
|scanu| scanu -- Compute the waveform and the wavetable for use in scanned
	synthesis.
|schedkwhen| schedkwhen -- Adds a new score event generated by a k-rate
	trigger.
|schedkwhennamed| schedkwhennamed -- Similar to schedkwhen but uses a named
	instrument at init-time.
|schedule| schedule -- Adds a new score event.
|schedwhen| schedwhen -- Adds a new score event.
|seed| seed -- Sets the global seed value.
|sekere| sekere -- Semi-physical model of a sekere sound.
|semitone| semitone -- Calculates a factor to raise/lower a frequency by a
	given amount of semitones.
|sense| sense -- Same as the sensekey opcode.
|sensekey| sensekey -- Returns the ASCII code of a key that has been pressed.
|seqtime| seqtime -- Generates a trigger signal according to the values stored
	in a table.
|setctrl| setctrl -- Configurable slider controls for realtime user input.
|setksmps| setksmps -- Sets the local ksmps value in a user-defined opcode
	block.
|sfilist| sfilist -- Prints a list of all instruments of a previously loaded
	SoundFont2 (SF2) file.
|sfinstr| sfinstr -- Plays a SoundFont2 (SF2) sample instrument, generating a
	stereo sound.
|sfinstr3| sfinstr3 -- Plays a SoundFont2 (SF2) sample instrument, generating
	a stereo sound with cubic interpolation.
|sfinstr3m| sfinstr3m -- Plays a SoundFont2 (SF2) sample instrument,
	generating a mono sound with cubic interpolation.
|sfinstrm| sfinstrm -- Plays a SoundFont2 (SF2) sample instrument, generating
	a mono sound.
|sfload| sfload -- Loads an entire SoundFont2 (SF2) sample file into memory.
|sfpassign| sfpassign -- Assigns all presets of a SoundFont2 (SF2) sample file
	to a sequence of progressive index numbers.
|sfplay| sfplay -- Plays a SoundFont2 (SF2) sample preset, generating a stereo
	sound.
|sfplay3| sfplay3 -- Plays a SoundFont2 (SF2) sample preset, generating a
	stereo sound with cubic interpolation.
|sfplay3m| sfplay3m -- Plays a SoundFont2 (SF2) sample preset, generating a
	mono sound with cubic interpolation.
|sfplaym| sfplaym -- Plays a SoundFont2 (SF2) sample preset, generating a mono
	sound.
|sfplist| sfplist -- Prints a list of all presets of a SoundFont2 (SF2) sample
	file.
|sfpreset| sfpreset -- Assigns an existing preset of a SoundFont2 (SF2) sample
	file to an index number.
|shaker| shaker -- Sounds like the shaking of a maraca or similar gourd
	instrument.
|sin| sin -- Performs a sine function.
|sinh| sinh -- Performs a hyperbolic sine function.
|sininv| sininv -- Performs an arcsine function.
|sleighbells| sleighbells -- Semi-physical model of a sleighbell sound.
|slider16| slider16 -- Creates a bank of 16 different MIDI control message
	numbers.
|slider16f| slider16f -- Creates a bank of 16 different MIDI control message
	numbers, filtered before output.
|slider32| slider32 -- Creates a bank of 32 different MIDI control message
	numbers.
|slider32f| slider32f -- Creates a bank of 32 different MIDI control message
	numbers, filtered before output.
|slider64| slider64 -- Creates a bank of 64 different MIDI control message
	numbers.
|slider64f| slider64f -- Creates a bank of 64 different MIDI control message
	numbers, filtered before output.
|slider8| slider8 -- Creates a bank of 8 different MIDI control message
	numbers.
|slider8f| slider8f -- Creates a bank of 8 different MIDI control message
	numbers, filtered before output.
|sndwarp| sndwarp -- Reads a mono sound sample from a table and applies
	time-stretching and/or pitch modification.
|sndwarpst| sndwarpst -- Reads a stereo sound sample from a table and applies
	time-stretching and/or pitch modification.
|soundin| soundin -- Reads audio data from an external device or stream.
|soundout| soundout -- Writes audio output to a disk file.
|space| space -- Distributes an input signal among 4 channels using cartesian
	coordinates.
|spat3d| spat3d -- Positions the input sound in a 3D space and allows moving
	the sound at k-rate.
|spat3di| spat3di -- Positions the input sound in a 3D space with the sound
	source position set at i-time.
|spat3dt| spat3dt -- Can be used to render an impulse response for a 3D space
	at i-time.
|spdist| spdist -- Calculates distance values from xy coordinates.
|specaddm| specaddm -- Perform a weighted add of two input spectra.
|specdiff| specdiff -- Finds the positive difference values between
	consecutive spectral frames.
|specdisp| specdisp -- Displays the magnitude values of the spectrum.
|specfilt| specfilt -- Filters each channel of an input spectrum.
|spechist| spechist -- Accumulates the values of successive spectral frames.
|specptrk| specptrk -- Estimates the pitch of the most prominent complex tone
	in the spectrum.
|specscal| specscal -- Scales an input spectral datablock with spectral
	envelopes.
|specsum| specsum -- Sums the magnitudes across all channels of the spectrum.
|spectrum| spectrum -- Generate a constant-Q, exponentially-spaced DFT.
|spsend| spsend -- Generates output signals based on a previously defined
	space opcode.
|sqrt| sqrt -- Returns a square root value.
|sr| sr -- Sets the audio sampling rate.
|stix| stix -- Semi-physical model of a stick sound.
|streson| streson -- A string resonator with variable fundamental frequency.
|strset| strset -- Allows a string to be linked with a numeric value.
|subinstr| subinstr -- Creates and runs a numbered instrument instance.
|subinstrinit| subinstrinit -- Creates and runs a numbered instrument instance
	at init-time.
|sum| sum -- Sums any number of a-rate signals.
|svfilter| svfilter -- A resonant second order filter, with simultaneous
	lowpass, highpass and bandpass outputs.
|table| table -- Accesses table values by direct indexing.
|table3| table3 -- Accesses table values by direct indexing with cubic
	interpolation.
|tablecopy| tablecopy -- Simple, fast table copy opcode.
|tablegpw| tablegpw -- Writes a table's guard point.
|tablei| tablei -- Accesses table values by direct indexing with linear
	interpolation.
|tableicopy| tableicopy -- Simple, fast table copy opcode.
|tableigpw| tableigpw -- Writes a table's guard point.
|tableikt| tableikt -- Provides k-rate control over table numbers.
|tableimix| tableimix -- Mixes two tables.
|tableiw| tableiw -- Change the contents of existing function tables.
|tablekt| tablekt -- Provides k-rate control over table numbers.
|tablemix| tablemix -- Mixes two tables.
|tableng| tableng -- Interrogates a function table for length.
|tablera| tablera -- Reads tables in sequential locations.
|tableseg| tableseg -- Creates a new function table by making linear segments
	between values in stored function tables.
|tablew| tablew -- Change the contents of existing function tables.
|tablewa| tablewa -- Writes tables in sequential locations.
|tablewkt| tablewkt -- Change the contents of existing function tables.
|tablexkt| tablexkt -- Reads function tables with linear, cubic, or sinc
	interpolation.
|tablexseg| tablexseg -- Creates a new function table by making exponential
	segments between values in stored function tables.
|tambourine| tambourine -- Semi-physical model of a tambourine sound.
|tan| tan -- Performs a tangent function.
|tanh| tanh -- Performs a hyperbolic tangent function.
|taninv| taninv -- Performs an arctangent function.
|taninv2| taninv2 -- Returns an arctangent.
|tbvcf| tbvcf -- Models some of the filter characteristics of a Roland TB303
	voltage-controlled filter.
|tempest| tempest -- Estimate the tempo of beat patterns in a control signal.
|tempo| tempo -- Apply tempo control to an uninterpreted score.
|tempoval| tempoval -- Reads the current value of the tempo.
|tigoto| tigoto -- Transfer control at i-time when a new note is being tied
	onto a previously held note
|timeinstk| timeinstk -- Read absolute time in k-rate cycles.
|timeinsts| timeinsts -- Read absolute time in seconds.
|timek| timek -- Read absolute time in k-rate cycles.
|times| times -- Read absolute time in seconds.
|timout| timout -- Conditional branch during p-time depending on elapsed note
	time.
|tival| tival -- Puts the value of the instrument's internal "tie-in" flag
	into the named i-rate variable.
|tlineto| tlineto -- Generate glissandos starting from a control signal.
|tone| tone -- A first-order recursive low-pass with variable frequency
	response.
|tonek| tonek -- A first-order recursive low-pass filter with variable
	frequency response.
|tonex| tonex -- Emulates a stack of filters using the tone opcode.
|transeg| transeg -- Constructs a user-definable envelope.
|trigger| trigger -- Informs when a krate signal crosses a threshold.
|trigseq| trigseq -- Accepts a trigger signal as input and outputs a group of
	values.
|trirand| trirand -- Linear distribution random number generator.
|turnoff| turnoff -- Enables an instrument to turn itself off.
|turnon| turnon -- Activate an instrument for an indefinite time.
|unirand| unirand -- Uniform distribution random number generator (positive
	values only).
|upsamp| upsamp -- Modify a signal by up-sampling.
|urd| urd -- A discrete user-defined-distribution random generator that can be
	used as a function.
|valpass| valpass -- Variably reverberates an input signal with a flat
	frequency response.
|vbap16| vbap16 -- Distributes an audio signal among 16 channels.
|vbap16move| vbap16move -- Distribute an audio signal among 16 channels with
	moving virtual sources.
|vbap4| vbap4 -- Distributes an audio signal among 4 channels.
|vbap4move| vbap4move -- Distributes an audio signal among 4 channels with
	moving virtual sources.
|vbap8| vbap8 -- Distributes an audio signal among 8 channels.
|vbap8move| vbap8move -- Distributes an audio signal among 8 channels with
	moving virtual sources.
|vbaplsinit| vbaplsinit -- Configures VBAP output according to loudspeaker
	parameters.
|vbapz| vbapz -- Writes a multi-channel audio signal to a ZAK array.
|vbapzmove| vbapzmove -- Writes a multi-channel audio signal to a ZAK array
	with moving virtual sources.
|vco| vco -- Implementation of a band limited, analog modeled oscillator.
|vco2| vco2 -- Implementation of a band-limited oscillator using
	pre-calculated tables.
|vco2ft| vco2ft -- Returns a table number at k-time for a given oscillator
	frequency and wavform.
|vco2ift| vco2ift -- Returns a table number at i-time for a given oscillator
	frequency and wavform.
|vco2init| vco2init -- Calculates tables for use by vco2 opcode.
|vcomb| vcomb -- Variably reverberates an input signal with a "colored"
	frequency response.
|vdelay| vdelay -- An interpolating variable time delay.
|vdelay3| vdelay3 -- An variable time delay with cubic interpolation.
|vdelayx| vdelayx -- A variable delay opcode with high quality interpolation.
|vdelayxq| vdelayxq -- A 4-channel variable delay opcode with high quality
	interpolation.
|vdelayxs| vdelayxs -- A stereo variable delay opcode with high quality
	interpolation.
|vdelayxw| vdelayxw -- Variable delay opcodes with high quality interpolation.
|vdelayxwq| vdelayxwq -- Variable delay opcodes with high quality
	interpolation.
|vdelayxws| vdelayxws -- Variable delay opcodes with high quality
	interpolation.
|veloc| veloc -- Get the velocity from a MIDI event.
|vibes| vibes -- Physical model related to the striking of a metal block.
|vibr| vibr -- Easier-to-use user-controllable vibrato.
|vibrato| vibrato -- Generates a natural-sounding user-controllable vibrato.
|vincr| vincr -- Accumulates audio signals.
|vlowres| vlowres -- A bank of filters in which the cutoff frequency can be
	separated under user control.
|voice| voice -- An emulation of a human voice.
|vpvoc| vpvoc -- Implements signal reconstruction using an fft-based phase
	vocoder and an extra envelope.
|waveset| waveset -- A simple time stretch by repeating cycles.
|weibull| weibull -- Weibull distribution random number generator (positive
	values only).
|wgbow| wgbow -- Creates a tone similar to a bowed string.
|wgbowedbar| wgbowedbar -- A physical model of a bowed bar.
|wgbrass| wgbrass -- Creates a tone related to a brass instrument.
|wgclar| wgclar -- Creates a tone similar to a clarinet.
|wgflute| wgflute -- Creates a tone similar to a flute.
|wgpluck| wgpluck -- A high fidelity simulation of a plucked string.
|wgpluck2| wgpluck2 -- Physical model of the plucked string.
|wguide1| wguide1 -- A simple waveguide model consisting of one delay-line and
	one first-order lowpass filter.
|wguide2| wguide2 -- A model of beaten plate consisting of two parallel
	delay-lines and two first-order lowpass filters.
|wrap| wrap -- Wraps-around the signal that exceeds the low and high
	thresholds.
|wterrain| wterrain -- A simple wave-terrain synthesis opcode.
|xadsr| xadsr -- Calculates the classical ADSR envelope.
|xin| xin -- Passes variables from a user-defined opcode block,
|xout| xout -- Retrieves variables from a user-defined opcode block,
|xscanmap| xscanmap -- Allows the position and velocity of a node in a scanned
	process to be read.
|xscansmap| xscansmap -- Allows the position and velocity of a node in a
	scanned process to be read.
|xscans| xscans -- Fast scanned synthesis waveform and the wavetable
	generator.
|xscanu| xscanu -- Compute the waveform and the wavetable for use in scanned
	synthesis.
|xtratim| xtratim -- Extend the duration of real-time generated events.
|xyin| xyin -- Sense the cursor position in an output window
|zacl| zacl -- Clears one or more variables in the za space.
|zakinit| zakinit -- Establishes zak space.
|zamod| zamod -- Modulates one a-rate signal by a second one.
|zar| zar -- Reads from a location in za space at a-rate.
|zarg| zarg -- Reads from a location in za space at a-rate, adds some gain.
|zaw| zaw -- Writes to a za variable at a-rate without mixing.
|zawm| zawm -- Writes to a za variable at a-rate with mixing.
|zfilter2| zfilter2 -- Performs filtering using a transposed form-II digital
	filter lattice with radial pole-shearing and angular pole-warping.
|zir| zir -- Reads from a location in zk space at i-rate.
|ziw| ziw -- Writes to a zk variable at i-rate without mixing.
|ziwm| ziwm -- Writes to a zk variable to an i-rate variable with mixing.
|zkcl| zkcl -- Clears one or more variables in the zk space.
|zkmod| zkmod -- Facilitates the modulation of one signal by another.
|zkr| zkr -- Reads from a location in zk space at k-rate.
|zkw| zkw -- Writes to a zk variable at k-rate without mixing.
|zkwm| zkwm -- Writes to a zk variable at k-rate with mixing.
|scoregenstop| Score Statements and GEN Routines
|scorestatementsref| Score Statements
|a| a Statement (or Advance Statement) -- Advance score time by a specified
	amount.
|b| b Statement -- This statement resets the clock.
|e| e Statement -- This statement may be used to mark the end of the last
	section of the score.
|f| f Statement (or Function Table Statement) -- Causes a GEN subroutine to
	place values in a stored function table.
|i| i Statement (Instrument or Note Statement) -- Makes an instrument active
	at a specific time and for a certain duration.
|m| m Statement (Mark Statement) -- Sets a named mark in the score.
|n| n Statement -- Repeats a section.
|q| q Statement -- This statement may be used to quiet an instrument.
|r| r Statement (Repeat Statement) -- Starts a repeated section.
|s| s Statement -- Marks the end of a section.
|t| t Statement (Tempo Statement) -- Sets the tempo.
|v| v Statement -- Provides for locally variable time warping of score events.
|x| x Statement -- Skip the rest of the current section.
|scoregenref| GEN Routines
|gen01| GEN01 -- Transfers data from a soundfile into a function table.
|gen02| GEN02 -- Transfers data from immediate pfields into a function table.
|gen03| GEN03 -- Generates a stored function table by evaluating a polynomial.
|gen04| GEN04 -- Generates a normalizing function.
|gen05| GEN05 -- Constructs functions from segments of exponential curves.
|gen06| GEN06 -- Generates a function comprised of segments of cubic
	polynomials.
|gen07| GEN07 -- Constructs functions from segments of straight lines.
|gen08| GEN08 -- Generate a piecewise cubic spline curve.
|gen09| GEN09 -- Generate composite waveforms made up of weighted sums of
	simple sinusoids.
|gen10| GEN10 -- Generate composite waveforms made up of weighted sums of
	simple sinusoids.
|gen11| GEN11 -- Generates an additive set of cosine partials.
|gen12| GEN12 -- Generates the log of a modified Bessel function of the second
	kind.
|gen13| GEN13 -- Stores a polynomial whose coefficients derive from the
	Chebyshev polynomials of the first kind.
|gen14| GEN14 -- Stores a polynomial whose coefficients derive from Chebyshevs
	of the second kind.
|gen15| GEN15 -- Creates two tables of stored polynomial functions.
|gen16| GEN16 -- Creates a table from a starting value to an ending value.
|gen17| GEN17 -- Creates a step function from given x-y pairs.
|gen18| GEN18 -- Writes composite waveforms made up of pre-existing waveforms.
|gen19| GEN19 -- Generate composite waveforms made up of weighted sums of
	simple sinusoids.
|gen20| GEN20 -- Generates functions of different windows.
|gen21| GEN21 -- Generates tables of different random distributions.
|gen23| GEN23 -- Reads numeric values from a text file.
|gen24| GEN24 -- Reads numeric values from another allocated function-table
	and rescales them.
|gen25| GEN25 -- Construct functions from segments of exponential curves in
	breakpoint fashion.
|gen27| GEN27 -- Construct functions from segments of straight lines in
	breakpoint fashion.
|gen28| GEN28 -- Reads a text file which contains a time-tagged trajectory.
|gen30| GEN30 -- Generates harmonic partials by analyzing an existing table.
|gen31| GEN31 -- Mixes any waveform specified in an existing table.
|gen32| GEN32 -- Mixes any waveform, resampled with either FFT or linear
	interpolation.
|gen33| GEN33 -- Generate composite waveforms by mixing simple sinusoids.
|gen34| GEN34 -- Generate composite waveforms by mixing simple sinusoids.
|gen40| GEN40 -- Generates a random distribution using a distribution
	histogram.
|gen41| GEN41 -- Generates a random list of numerical pairs.
|gen42| GEN42 -- Generates a random distribution of discrete ranges of values.
|utilitytop| The Utility Programs
|utilitydir| Directories.
|utilitysoundfile| Soundfile Formats.
|utilitycredits| Credits
|utilityanalysis| Analysis File Generation
|hetro| hetro -- Decomposes an input soundfile into component sinusoids.
|lpanal| lpanal -- Performs both linear predictive analysis on a soundfile.
|pvanal| pvanal -- Converts a soundfile into a series of short-time Fourier
	transform frames.
|cvanal| cvanal -- Converts a soundfile into a single Fourier transform frame.
|utilityqueries| File Queries
|sndinfo| sndinfo -- Displays information about a soundfile.
|utilityconversion| File Conversion
|dnoise| dnoise -- Reduces noise in a file.
|pvlook| pvlook -- View formatted text output of STFT analysis files.
|sdif2ad| sdif2ad -- Converts SDIF files to files usable by adsynt.
|srconv| srconv -- Converts the sample rate of an audio file.
|cscoretop| Cscore
|cscoreevents| Events, Lists, and Operations
|cscoremain| Writing a Main Program
|cscoreadvancd| More Advanced Examples
|cscorecompile| Compiling a Cscore Program
|addmodtop| Adding your own Cmodules to Csound
|addmodftables| Function tables
|addmodaddspace| Additional Space
|addmodfsharing| File Sharing
|addmodstringargs| String arguments
|miscpitch| Pitch Conversion
|miscamp| Sound Intensity Values
|miscformants| Formant Values
|miscwindows| Window Functions
|miscsf2| SoundFont2 File Format
|misccsound64| Csound64

------------------------------------------------------------------------------
*prefacetop*
Preface	~

------------------------------------------------------------------------------
*prefacepreface*
Preface to the Csound Manual	~

Barry Vercoe

by Barry L. Vercoe, MIT Media Lab

Realizing music by digital computer involves synthesizing audio signals with
discrete points or samples representative of continuous waveforms. There are
many ways to do this, each affording a different manner of control. Direct
synthesis generates waveforms by sampling a stored function representing a
single cycle; additive synthesis generates the many partials of a complex
tone, each with its own loudness envelope; subtractive synthesis begins with
a complex tone and filters it. Non-linear synthesis uses frequency modulation
and waveshaping to give simple signals complex characteristics, while
sampling and storage of a natural sound allows it to be used at will.

Since comprehensive moment-by-moment specification of sound can be tedious,
control is gained in two ways: 1) from the instruments in an orchestra, and
2) from the events within a score. An orchestra is really a computer program
that can produce sound, while a score is a body of data which that program
can react to. Whether a rise-time characteristic is a fixed constant in an
instrument, or a variable of each note in the score, depends on how the user
wants to control it.

The instruments in a Csound orchestra (see |orchtop| ) are defined in a
simple syntax that invokes complex audio processing routines. A score (see
|scoretop| ) passed to this orchestra contains numerically coded pitch and
control information, in standard numeric score format. Although many users
are content with this format, higher level score processing languages are
often convenient.

The programs making up the Csound system have a long history of development,
beginning with the Music 4 program written at Bell Telephone Laboratories in
the early 1960's by Max Mathews. That initiated the stored table concept and
much of the terminology that has since enabled computer music researchers to
communicate. Valuable additions were made at Princeton by the late Godfrey
Winham in Music 4B; my own Music 360 (1968) was very indebted to his work.
With Music 11 (1973) I took a different tack: the two distinct networks of
control and audio signal processing stemmed from my intensive involvement in
the preceding years in hardware synthesizer concepts and design. This
division has been retained in Csound.

Because it is written entirely in C, Csound is easily installed on any
machine running Unix or C. At MIT it runs on VAX/DECstations under Ultrix
4.2, on SUNs under OS 4.1, SGI's under 5.0, on IBM PC's under DOS 6.2 and
Windows 3.1, and on the Apple Macintosh under ThinkC 5.0. With this single
language for defining the audio signal processing, and portable audio formats
like AIFF and WAV, users can move easily from machine to machine.

The 1991 version added phase vocoder, FOF, and spectral data types. 1992 saw
MIDI converter and control units, enabling Csound to be run from MIDI
score-files and external keyboards. In 1994 the sound analysis programs (lpc,
pvoc) were integrated into the main load module, enabling all Csound
processing to be run from a single executable, and Cscore could pass scores
directly to the orchestra for iterative performance. The 1995 release
introduced an expanded MIDI set with MIDI-based linseg, butterworth filters,
granular synthesis, and an improved spectral-based pitch tracker. Of special
importance was the addition of run-time event generating tools (Cscore and
MIDI) allowing run-time sensing and response setups that enable interactive
composition and experiment. It appeared that real-time software synthesis was
now showing some real promise.

------------------------------------------------------------------------------
*prefacecopy*
Copyright Notice	~

Copyright (c) 1986, 1992 by the Massachusetts Institute of Technology. All
rights reserved.

Developed by Barry L. Vercoe at the Experimental Music Studio, Media
Laboratory, M.I.T., Cambridge, Massachusetts, with partial support from the
System Development Foundation and from National Science Foundation Grant #
IRI-8704665.

Copyright (c) 2003 by Kevin Conder for modifications made to the Public
Csound Reference Manual.

Permission is granted to copy, distribute and/or modify this document under
the terms of the GNU Free Documentation License, Version 1.2 or any later
version published by the Free Software Foundation; with no Invariant
Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of this
license is available in the examples sub-directory.

A legal notice from the Public Csound Reference Manual... "The original
Hypertext Edition of the MIT Csound Manual was prepared for the World Wide
Web by Peter J. Nix of the Department of Music at the University of Leeds and
Jean Piché of the Faculté de musique de l'Université de Montréal. A Print
Edition, in Adobe Acrobat format, was then maintained by David M. Boothe. The
editors fully acknowledge the rights of the authors of the original
documentation and programs, as set out above, and further request that this
notice appear wherever this material is held."

The Public Csound Reference Manual's last known network location was
http://www.lakewoodsound.com/csound/hypertext/manual.htm.

The Alternative Csound Reference Manual's network location, for both the
Transparent and Opaque copies, is
http://kevindumpscore.com/download.html#csound-manual.

------------------------------------------------------------------------------
*prefaceacknowledgements*
Acknowledgements	~

In addition to the core code developed by Barry L. Vercoe at M.I.T., a large
part of the Csound code was modified, developed and extended by an
independent group of programmers, composers and scientists. Copyright to this
code is held by the respective authors:

Table 1. Contributors

 Mike Berry      Richard Karpen     
 Eli Breder      Victor Lazzarini   
 Michael Casey   Allan Lee          
 Michael Clark   David Macintyre    
 Perry Cook      Gabriel Maldonado  
 Sean Costello   Max Mathews        
 Richard Dobson  Hans Mikelson      
 Mark Dolson     Peter Neubäcker    
 Rasmus Ekman    Ville Pulkki       
 Dan Ellis       Marc Resibois      
 Tom Erbe        Paris Smaragdis    
 John ffitch     Rob Shaw           
 Bill Gardner    Greg Sullivan      
 Matt Ingalls    Bill Verplank      
 Istvan Varga    Robin Whittle      
 Jean Piché      Peter Nix          

The official manual was compiled from the canonical Csound Manual sources
maintained by John ffitch, Richard Boulanger, Jean Piché, Peter Nix, and
David M. Boothe. The Alternative Csound Reference Manual is maintained by
Kevin Conder.

------------------------------------------------------------------------------
*prefacename*
Why is this called the Alternative Csound Reference Manual?	~

When I originally started my manual project, there was already an Official
Csound Reference Manual (last known address:
http://www.lakewoodsound.com/csound/hypertext/manual.htm). The Official
manual was maintained by David M. Boothe. I found its layout confusing and I
wanted to change it. But since it was maintained with a commercial word
processing program, I couldn't. I could neither afford this program nor was
it available for my main computing platform.

So I created an alternative to the Official Csound Reference Manual. I
distributed my manual using the DocBook/SGML format so that anyone on any
platform could edit it with a text editor. This manual can also be produced
with freely available programs.

David M. Boothe wasn't interested in maintaining my DocBook/SGML version of
the manual. He was also concerned that people would confuse his project (the
"Official" one) with mine. So out of respect for his wishes, I named my
project the Alternative Csound Reference Manual. I made this decision so that
nobody would confuse my project (the "Alternative" one) with his.

Written by Kevin Conder, October 2002.

------------------------------------------------------------------------------
*prefacescope*
What is the scope of the Alternative Csound Reference Manual?	~

While there are numerous Csound-related projects, this manual only covers the
canonical Csound program. This program is maintained by John ffitch and is
stored on the Bath University FTP server
(ftp://www.cs.bath.ac.uk/pub/dream/newest/). I apologize that I can't
maintain the documentation for other projects. I simply don't have the time
and resources to do so.

Written by Kevin Conder, January 2003.

------------------------------------------------------------------------------
*prefacecsoundav*
Where is the documentation for the CsoundAV project?	~

The documentation for the CsoundAV project is located at
http://www.csounds.com/csoundav/index.html.

*partoverview*

Overview	~

Table of Contents

|introtop| Introduction
|commandtop| The Csound Command
|orchtop| Syntax of the Orchestra
|controltop| Instrument Control
|tabletop| Function Table Control
|mathtop| Mathematical Operations
|miditop| MIDI Support
|pitchtop| Pitch Converters
|siggentop| Signal Generators
|sigiotop| Signal Input and Output
|sigmodtop| Signal Modifiers
|spectraltop| Spectral Processing
|zaktop| Zak Patch System
|scoretop| The Standard Numeric Score

------------------------------------------------------------------------------
*introtop*
Introduction	~

------------------------------------------------------------------------------
*introget*
Where to Get Public Csound and the Csound Manual	~

Public Csound is available for download from :

ftp://ftp.cs.bath.ac.uk/pub/dream/newest/

This Hypertext Edition of the manual, as well as the Print Edition, in Adobe
Acrobat format (.pdf) are available for browser download from:

http://www.kevindumpscore.com/download/

------------------------------------------------------------------------------
*introinstall*
How to Install Csound	~

------------------------------------------------------------------------------
*introinstalllinux*
Linux	~

Detailed instructions for installing and configuring Csound on a Linux system
may be obtained from:

http://www.csounds.com/secondprinting/cdroms/installing/linux/

------------------------------------------------------------------------------
*introinstallmac*
Macintosh	~

Detailed instructions for installing and configuring Csound on Macintosh
systems may be obtained from:

http://www.csounds.com/installing/howtomacintosh/index.html

------------------------------------------------------------------------------
*introinstallmsdos*
MS-DOS and Windows 95/NT	~

Detailed instructions for installing and configuring Csound on a MS-DOS or
Windows 95/NT system may be obtained from:

http://hem.passagen.se/rasmuse/PCinstal.htm

------------------------------------------------------------------------------
*introinstallwindow*
Windows 95/98/2000	~

Detailed instructions for installing and configuring Csound on a Windows 95,
Windows 98, or Windows 2000 system may be obtained from:

http://www.csounds.com/installing/howtowindows/index.html

------------------------------------------------------------------------------
*introinstallother*
Other Platforms	~

For information on availability of Csound for other platforms, see The Csound
FrontPage:

http://mitpress.mit.edu/e-books/csound/frontpage.html

------------------------------------------------------------------------------
*introlist*
The Csound Mailing List	~

A Csound Mailing List exists to discuss Csound. It is run by John ffitch of
Bath University, UK.

To have your name put on the mailing list send an empty message to:

csound-subscribe@lists.bath.ac.uk

Posts sent to csound@lists.bath.ac.uk go to all subscribed members of the
list.

------------------------------------------------------------------------------
*introlistbugs*
Bug Reports	~

Suspected bugs in the code may be entered using the bug tracking system at
http://www.cs.bath.ac.uk/cgi-bin/csound.

------------------------------------------------------------------------------
*commandtop*
The Csound Command	~

Csound is a command for passing anorchestra file andscore file to Csound to
generate a soundfile. The score file can be in one of many different formats,
according to user preference. Translation, sorting, and formatting into
orchestra-readable numeric text is handled by various preprocessors; all or
part of the score is then sent on to the orchestra. Orchestra performance is
influenced by command flags, which set the level of displays and console
reports, specify I/0 filenames and sample formats, and declare the nature of
real-time sensing and control.

------------------------------------------------------------------------------
*commandorder*
Order of Precedence	~

With some recent additions to Csound, there are now three places (and in some
cases four) where options for Csound performance may be set. They are
processed in the following order:

 1. Csound's own defaults

 2. .csoundrc file

 3. Csound command line

 4. <CsOptions> tag in a .csd file

 5. Orchestra header (for sr, kr, ksmps, nchnls)

The last assignment of an option will override any earlier ones.

------------------------------------------------------------------------------
*commanddesc*
Description	~

Flags may appear anywhere in the command line, either separately or bundled
together. A flag taking a Name or Number will find it in that argument, or in
the immediately subsequent one. The following are thus equivalent commands:

 csound -nm3 orchname -Sxxfilename scorename
 csound -n -m 3 orchname -x xfilename -S scorename

All flags and names are optional. The default values are:

 csound -s -otest -b1024 -B1024 -m7 -P128 orchname scorename

where orchname is a file containing Csound orchestra code, and scorename is a
file of score data in standard numeric score format, optionally presorted and
time-warped. If scorename is omitted, there are two default options:

 1. if real-time input is expected (-L, -M or -F), a dummy score file is
    substituted consisting of the single statement 'f 0 3600' (i.e. listen
    for RT input for one hour)

 2. else CSound uses the previously processed score.srt in the current
    directory.

Csound reports on the various stages of score and orchestra processing as it
goes, doing various syntax and error checks along the way. Once the actual
performance has begun, any error messages will derive from either the
instrument loader or the unit generators themselves. A CSound command may
include any rational combination of flag arguments.

------------------------------------------------------------------------------
*commandflags*
Command-line Flags	~

Many flags are generic Csound command-line flags. Various platform
implementations may not react the same way to different flags!

The format of a command is either:

csound [-flags] [orchname] [scorename]

or

csound [-flags] [csdfilename]

where the arguments are of 2 types: flags arguments (beginning with a "-"),
and name arguments (such as filenames). Certain flag arguments take a
following name or numeric argument.

Command-line Flags

------------------------------------------------------------------------------
*flagsminusat*
-@ FILE	~

        Provide an extended command-line in file "FILE"

------------------------------------------------------------------------------
*flagsminus3*
-3, --format=24bit	~

        Use 24-bit audio samples.

------------------------------------------------------------------------------
*flagsminus8*
-8, --format=uchar	~

        Use 8-bit unsigned character audio samples.

------------------------------------------------------------------------------
*flagsminusuppera*
-A, --aiff	~

        Write an AIFF format soundfile. Use with the |flagsminuslowerc| -c,
        |flagsminuslowers| -s, |flagsminuslowerl| -l, or |flagsminuslowerf|
        -f flags.

------------------------------------------------------------------------------
*flagsminuslowera*
-a, --format=alaw	~

        Use a-law audio samples.

------------------------------------------------------------------------------
*flagsminusupperb*
-B NUM, --hardwarebufsamps=NUM	~

        Number of audio sample-frames held in the DAC hardware buffer. This
        is a threshold on which software audio I/O (above) will wait before
        returning. A small number reduces audio I/O delay; but the value is
        often hardware limited, and small values will risk data lates. The
        default is 1024.

------------------------------------------------------------------------------
*flagsminuslowerb*
-b NUM, --iobufsamps=NUM	~

        Number of audio sample-frames per sound i/o software buffer. Large is
        efficient, but small will reduce audio I/O delay. The default is
        1024. In real-time performance, Csound waits on audio I/O on NUM
        boundaries. It also processes audio (and polls for other input like
        MIDI) on orchestra ksmps boundaries. The two can be made synchronous.
        For convenience, if NUM = -NUM (is negative) the effective value is
        ksmps * NUM (audio synchronous with k-period boundaries). With NUM
        small (e.g. 1) polling is then frequent and also locked to fixed DAC
        sample boundaries.

------------------------------------------------------------------------------
*flagsminusupperc*
-C, --cscore	~

        Use Cscore processing of the scorefile.

------------------------------------------------------------------------------
*flagsminuslowerc*
-c, --format=schar	~

        Use 8-bit signed character audio samples.

------------------------------------------------------------------------------
*flagsminusupperd*
-D, --defer-gen1	~

        Defer GEN01 soundfile loads until performance time.

------------------------------------------------------------------------------
*flagsminuslowerd*
-d, --nodisplays	~

        Suppress all displays.

------------------------------------------------------------------------------
*flagsminusuppere*
-E NUM, --graphs=NUM	~

        Mac only. Number of tables in graphics window. (was -G)

------------------------------------------------------------------------------
*flagsminuslowere*
-e, --format=rescale	~

        Mac only. Rescale floats as shorts to max amplitude.

------------------------------------------------------------------------------
*flagsminusupperf*
-F FILE, --midifile=FILE	~

        Read MIDI events from MIDI file FILE.

------------------------------------------------------------------------------
*flagsminuslowerf*
-f, --format=float	~

        Use single-precision float audio samples (not playable, but can be
        read by |flagsminusloweri| -i, |soundin| soundin and |gen01| GEN01

------------------------------------------------------------------------------
*flagsminusupperg*
-G, --postscriptdisplay	~

        Suppress graphics, use PostScript displays instead.

------------------------------------------------------------------------------
*flagsminuslowerg*
-g, --asciidisplay	~

        Suppress graphics, use ASCII displays instead.

------------------------------------------------------------------------------
*flagsminusupperh*
-H#, --heartbeat=NUM	~

        Print a heartbeat after each soundfile buffer write:

           * no NUM, a rotating bar.

           * NUM = 1, a rotating bar.

           * NUM = 2, a dot (.)

           * NUM = 3, filesize in seconds.

           * NUM = 4, sound a bell.

------------------------------------------------------------------------------
*flagsminuslowerh*
-h, --noheader	~

        No header on output soundfile. Don't write a file header, just binary
        samples.

------------------------------------------------------------------------------
*flagsminushelp*
--help	~

        Display on-line help message.

------------------------------------------------------------------------------
*flagsminusupperi*
-I, --i-only	~

        i-time only. Allocate and initialize all instruments as per the
        score, but skip all p-time processing (no k-signals or a-signals, and
        thus no amplitudes and no sound). Provides a fast validity check of
        the score pfields and orchestra i-variables.

------------------------------------------------------------------------------
*flagsminusloweri*
-i FILE, --input=FILE	~

        Input soundfile name. If not a full pathname, the file will be sought
        first in the current directory, then in that given by the environment
        variable SSDIR (if defined), then by SFDIR. The name stdin will cause
        audio to be read from standard input. If RTAUDIO is enabled, the name
        devaudio will request sound from the host audio input device.

------------------------------------------------------------------------------
*flagsminusupperj*
-J, --ircam	~

        Write an IRCAM format soundfile.

------------------------------------------------------------------------------
*flagsminuslowerj*
-j FILE	~

        Currently disabled. Use database FILE for messages to print to
        console during performance.

------------------------------------------------------------------------------
*flagsminusupperk*
-K, --nopeaks	~

        Do not generate any PEAK chunks.

------------------------------------------------------------------------------
*flagsminuslowerk*
-k NUM, --control-rate=NUM	~

        Override the control rate (|kr| KR) supplied by the orchestra.

------------------------------------------------------------------------------
*flagsminusupperl*
-L DEVICE, --score-in=DEVICE	~

        Read line-oriented real-time score events from device DEVICE. The
        name stdin will permit score events to be typed at your terminal, or
        piped from another process. Each line-event is terminated by a
        carriage-return. Events are coded just like those in a standard
        numeric score, except that an event with p2=0 will be performed
        immediately, and an event with p2=T will be performed T seconds after
        arrival. Events can arrive at any time, and in any order. The score
        carry feature is legal here, as are held notes (p3 negative) and
        string arguments, but ramps and pp or np references are not.

------------------------------------------------------------------------------
*flagsminuslowerl*
-l, --format=long	~

        Use long integer audio samples.

------------------------------------------------------------------------------
*flagsminusupperm*
-M DEVICE, --midi-device=DEVICE	~

        Read MIDI events from device DEVICE.

------------------------------------------------------------------------------
*flagsminuslowerm*
-m NUM, --messagelevel=NUM	~

        Message level for standard (terminal) output. Takes the sum of 3
        print control flags, turned on by the following values:

           * 1 = note amplitude messages

           * 2 = samples out of range message

           * 4 = warning messages

        The default value is m7 (all messages on).

------------------------------------------------------------------------------
*flagsminusuppern*
-N, --notify	~

        Notify (ring the bell) when score or MIDI track is done.

------------------------------------------------------------------------------
*flagsminuslowern*
-n, --nosound	~

        No sound. Do all processing, but bypass writing of sound to disk.
        This flag does not change the execution in any other way.

------------------------------------------------------------------------------
*flagsminusuppero*
-O FILE, --logfile=FILE	~

        Log output to file FILE.

------------------------------------------------------------------------------
*flagsminuslowero*
-o FILE, --output=FILE	~

        Output soundfile name. If not a full pathname, the soundfile will be
        placed in the directory given by the environment variable SFDIR (if
        defined), else in the current directory. The name stdout will cause
        audio to be written to standard output. If no name is given, the
        default name will be test. If RTAUDIO is enabled, the name devaudio
        will send to the host audio output device.

------------------------------------------------------------------------------
*flagsminusupperp*
-P NUM, --pollrate=NUM	~

        Mac only. Poll events every NUM buffer writes.

------------------------------------------------------------------------------
*flagsminuslowerp*
-p, --play-on-end	~

        Mac only. Play after rendering.

------------------------------------------------------------------------------
*flagsminusupperq*
-Q DEVICE, -Q DIRECTORY, --analysis-directory=DIRECTORY	~

        Beos and Linux only. Enables MIDI OUT operations and optionally
        chooses device id DEVICE (if the DEVICE argument is present). This
        flag allows parallel MIDI OUT and DAC performance. Unfortunately the
        real-time timing implemented in Csound is completely managed by DAC
        buffer sample flow. So MIDI OUT operations can present some time
        irregularities. These irregularities can be fully eliminated when
        suppressing DAC operations themselves (see |flagsminusuppery| -Y
        flag).

        Mac only. Define the analysis (SADIR) directory.

------------------------------------------------------------------------------
*flagsminuslowerq*
-q DIRECTORY, --sample-directory=DIRECTORY	~

        Mac only. Define the sound sample-in (SSDIR) directory.

------------------------------------------------------------------------------
*flagsminusupperr*
-R, --rewrite	~

        Continually rewrite the header while writing the soundfile
        (WAV/AIFF).

------------------------------------------------------------------------------
*flagsminuslowerr*
-r NUM, --sample-rate=NUM	~

        Override the sampling rate (|sr| SR) supplied by the orchestra.

------------------------------------------------------------------------------
*flagsminuslowers*
-s, --format=short	~

        Use short integer audio samples.

------------------------------------------------------------------------------
*flagsminussched*
--sched	~

        Linux only. Use real-time scheduling and lock memory. (Also requires
        |flagsminuslowerd| -d and either |flagsminuslowero| -o dac or
        |flagsminuslowero| -o devaudio).

------------------------------------------------------------------------------
*flagsminusuppert*
-T, --terminate-on-midi	~

        Terminate the performance when MIDI track is done.

------------------------------------------------------------------------------
*flagsminuslowert0*
-t0, --keep-sorted-score	~

        Prevents Csound from deleting the sorted score file, score.srt, upon
        exit.

------------------------------------------------------------------------------
*flagsminuslowert*
-t NUM, --tempo=NUM	~

        Use the uninterpreted beats of score.srt for this performance, and
        set the initial tempo at NUM beats per minute. When this flag is set,
        the tempo of score performance is also controllable from within the
        orchestra.

------------------------------------------------------------------------------
*flagsminusupperu*
-U UTILITY, --utility=UTILITY	~

        Invoke the utility program UTILITY.

------------------------------------------------------------------------------
*flagsminusloweru*
-u, --format=ulaw	~

        Use u-law audio samples.

------------------------------------------------------------------------------
*flagsminusupperv*
-V NUM, --screen-buffer=NUM, --volume=NUM	~

        Linux only. Set real-time audio output volume to NUM (1 to 100).

        Mac only. Number of chars in the screen buffer for the output window.

------------------------------------------------------------------------------
*flagsminuslowerv*
-v, --verbose	~

        Verbose translate and run. Prints details of orch translation and
        performance, enabling errors to be more clearly located.

------------------------------------------------------------------------------
*flagsminusupperw*
-W, --wave	~

        Write a WAV format soundfile.

------------------------------------------------------------------------------
*flagsminuslowerw*
-w, --save-midi	~

        Mac only. Record and save MIDI input to a file.

------------------------------------------------------------------------------
*flagsminusupperx*
-X DIRECTORY, --sound-directory=DIRECTORY	~

        Mac only. Define the sound file (SFDIR) directory.

------------------------------------------------------------------------------
*flagsminuslowerx*
-x FILE, --extract-score=FILE	~

        Extract a portion of the sorted score, score.srt, using the extract
        file FILE (see |commandpreextract| Extract).

------------------------------------------------------------------------------
*flagsminusuppery*
-Y NUM, --progress-rate=NUM	~

        Currently disabled. Mac only. Enables progress display at rate NUM in
        seconds, or for negative NUM, at -NUM kperiods.

------------------------------------------------------------------------------
*flagsminuslowery*
-y NUM, --profile-rate=NUM	~

        Currently disabled. Mac only. Enables profile display at rate NUM in
        seconds, or for negative NUM, at -NUM kperiods.

------------------------------------------------------------------------------
*flagsminusupperz*
-Z, --dither	~

        Switch on dithering of audio conversion from internal floating point
        to 32, 16 and 8-bit formats.

------------------------------------------------------------------------------
*flagsminuslowerz*
-z NUM, --list-opcodesNUM	~

        List opcodes in this version:

           * no NUM, just show names

           * NUM = 0, just show names

           * NUM = 1, show arguments to each opcode using the format <opname>
             <inargs> <outargs>

------------------------------------------------------------------------------
*commandunifile*
Unified File Format for Orchestras and Scores	~

Description		~

The Unified File Format , introduced in Csound version 3.50, enables the
orchestra and score files, as well as command line flags, to be combined in
one file. The file has the extension .csd. This format was originally
introduced by Michael Gogins in AXCsound.

The file is a structured data file which uses markup language, similar to any
SGML such as HTML. Start tags (<tag>) and end tags (</tag>) are used to
delimit the various elements. The file is saved as a text file.

Structured Data File Format

Mandatory Elements

The Csound Element is used to alert the csound compiler to the .csd format.
The file must begin with the start tag <CsoundSynthesizer>. The last line of
the file must be the end tag </CsoundSynthesizer>. The remaining elements are
defined below.

 Options

Csound command line flags are put in the Options Element. This section is
delimited by the start tag <CsOptions> and the end tag </CsOptions> Lines
beginning with # or ; are treated as comments.

 Instruments (Orchestra)

The instrument definitions (orchestra) are put into the Instruments Element.
The statements and syntax in this section are identical to the Csound
orchestra file, and have the same requirements, including the header
statements (sr, kr, etc.) This Instruments Element is delimited with the
start tag <CsInstruments> and the end tag </CsInstruments>.

 Score

Csound score statements are put in the Score Element. The statements and
syntax in this section are identical to the Csound score file, and have the
same requirements. The Score Element is delimited by the start tag <CsScore>
and the end tag </CsScore>.

Optional Elements

 Included Base64 Files

Base64 encoded MIDI files may be included with the tag <CsMidifileB
filename=filename>, where filename is the name of the file containing the
MIDI information. There is no matching end tag. New in Csound version 4.07.

Base64 encoded sample files may be included with the tag <CsSampleB
filename=filename>, where filename is the name of the file containing the
sample. There is no matching end tag. New in Csound version 4.07.

 Version Blocking

Versions of Csound may blocked by placing one of the following statements
between the start tag <CsVersion> and the end tag </CsVersion>:

 Before #.#

or

 After #.#

where #.# is the requested Csound version number. The second statement may be
written simply as:

 #.#

See example below. New in Csound version 4.09.

Example		~

Below is a sample file, test.csd, which renders a .wav file at 44.1 kHz
sample rate containing one second of a 1 kHz sine wave. Displays are
suppressed. test.csd was created from two files, tone.orc and tone.sco, with
the addition of command line flags.

 <CsoundSynthesizer>;
; test.csd - a Csound structured data file

 <CsOptions>
csound -W -d -o tone.wav
 </CsOptions>

 <CsVersion>    ;optional section
Before 4.10  ;these two statements check for
After 4.08   ;   Csound version 4.09
 </CsVersion>

 <CsInstruments>
; originally tone.orc
sr = 44100
kr = 4410
ksmps = 10
nchnls = 1
instr   1
    a1 oscil p4, p5, 1 ; simple oscillator
       out a1
  endin
 </CsInstruments>

 <CsScore>
; originally tone.sco
f1 0 8192 10 1
i1 0 1 20000 1000 ;play one second of one kHz tone
e
 </CsScore>

 </CsoundSynthesizer>

Command Line Parameter File

If the file .csoundrc exists, it will be used to set the command line
parameters. These can be overridden. It uses the same form as a .csd file.
Lines beginning with # or ; are treated as comments.

------------------------------------------------------------------------------
*commandpreproc*
Score File Preprocessing	~

------------------------------------------------------------------------------
*commandpreextract*
The Extract Feature	~

This feature will extract a segment of a sorted numeric score file according
to instructions taken from a control file. The control file contains an
instrument list and two time points, from and to, in the form:

 instruments 1  2  from  1:27.5  to  2:2

The component labels may be abbreviated as i, f and t. The time points denote
the beginning and end of the extract in terms of:

 [section no.] : [beat no.].

each of the three parts is also optional. The default values for missing i, f
or t are:

 all instruments, beginning of score, end of score.

------------------------------------------------------------------------------
*commandpreindie*
Independent Pre-Processing with Scsort	~

Although the result of all score preprocessing is retained in the file
score.srt after orchestra performance (it exists as soon as score
preprocessing has completed), the user may sometimes want to run these phases
independently. The command

 scot filename

will process the Scot formatted filename, and leave a |scoretop| standard
numeric score result in a file named score for perusal or later processing.

The command

 scscort < infile > outfile

will put a numeric score infile through Carry, Tempo, and Sort preprocessing,
leaving the result in outfile.

Likewise extract, also normally invoked as part of the |commandtop| Csound
command, can be invoked as a standalone program:

 extract xfile < score.sort > score.extract

This command expects an already sorted score. An unsorted score should first
be sent through Scsort then piped to the extract program:

  scsort < scorefile | extract xfile > score.extract

------------------------------------------------------------------------------
*orchtop*
Syntax of the Orchestra	~

An orchestra statement in Csound has the format:

label: result opcode argument1, argument2, ... ;comments

The label is optional and identifies the basic statement that follows as the
potential target of a go-to operation (see |controlpgmctl| Program Flow
Control). A label has no effect on the statement per se.

Comments are optional and are for the purpose of letting the user document
his orchestra code. Comments always begin with a semicolon (;) and extend to
the end of the line.

The remainder (result, opcode, and arguments) form the basic statement. This
also is optional, i.e. a line may have only a label or comment or be entirely
blank. If present, the basic statement must be complete on one line, and is
terminated by a carriage return and line feed.

The opcode determines the operation to be performed; it usually takes some
number of input values (or arguments, with a maximum value of about 800); and
it usually has a result field variable to which it sends output values at
some fixed rate. There are four possible rates:

 1. once only, at orchestra setup time (effectively a permanent assignment)

 2. once at the beginning of each note (at initialization (init) time:
    i-rate)

 3. once every performance-time control loop (perf-time control rate, or
    k-rate)

 4. once each sound sample of every control loop (perf-time audio rate, or
    a-rate)

------------------------------------------------------------------------------
*orchdirfiles*
Directories and Files	~

Many generators and the Csound command itself specify filenames to be read
from or written to. These are optionally full pathnames, whose target
directory is fully specified. When not a full path, filenames are sought in
several directories in order, depending on their type and on the setting of
certain environment variables. The latter are optional, but they can serve to
partition and organize the directories so that source files can be shared
rather than duplicated in several user directories. The environment variables
can define directories for soundfiles SFDIR, sound samples SSDIR, sound
analysis SADIR, and include files for orchestra and score files INCDIR.

The search order is:

 1. Soundfiles being written are placed in SFDIR (if it exists), else the
    current directory.

 2. Soundfiles for reading are sought in the current directory, then SSDIR,
    then SFDIR.

 3. Analysis control files for reading are sought in the current directory,
    then SADIR.

 4. Files of code to be included in orchestra and score files (with |include|
    #include) are sought first in the current directory, then in the same
    directory as the orchestra or score file (as appropriate), then finally
    INCDIR.

Beginning with Csound version 3.54, the file "csound.txt" contains the
messages (in binary format) that Csound uses to provide information to the
user during performance. This allows for the messages to be in any language,
although the default is English. This file must be placed in the same
directory as the Csound executable. Alternatively, this file may be stored in
SFDIR, SSDIR, or SADIR. Unix users may also keep this file in
"/usr/local/lib/". The environment variable CSSTRNGS may be used to define
the directory in which the database resides. This can be overridden with the
-j command line option. (New in version 3.55)

------------------------------------------------------------------------------
*orchnomen*
Nomenclature	~

Throughout this document, opcodes are indicated in boldface and their
argument and result mnemonics, when mentioned in the text, are given in
italics. Argument names are generally mnemonic (amp, phs), and the result is
usually denoted by the letter r. Both are preceded by a type qualifier i, k,
a, or x (e.g. kamp, iphs, ar). The prefix i denotes scalar values valid at
note init time; prefixes k or a denote control (scalar) and audio (vector)
values, modified and referenced continuously throughout performance (i.e. at
every control period while the instrument is active). Arguments are used at
the prefix-listed times; results are created at their listed times, then
remain available for use as inputs elsewhere. With few exceptions, argument
rates may not exceed the rate of the result. The validity of inputs is
defined by the following:

  * arguments with prefix i must be valid at init time;

  * arguments with prefix k can be either control or init values (which
    remain valid);

  * arguments with prefix a must be vector inputs;

  * arguments with prefix x may be either vector or scalar (the compiler will
    distinguish).

All arguments, unless otherwise stated, can be expressions whose results
conform to the above. Most opcodes (such as linen and oscil) can be used in
more than one mode, which one being determined by the prefix of the result
symbol.

Thoughout this manual, the term "opcode" is used to indicate a command that
usually produces an a-, k-, or i-rate output, and always forms the basis of a
complete Csound orchestra statement. Items such as "+" or "sin(x)" or, "( a
>= b ? c : d)" are called "operators."

------------------------------------------------------------------------------
*orchstatemnt*
Orchestra Statement Types	~

An orchestra program in Csound is comprised of |orchheader| orchestra header
statements which set various global parameters, followed by a number of
|orchiblock| instrument blocks representing different instrument types. An
instrument block, in turn, is comprised of ordinary statements that set
values, control the logical flow, or invoke the various signal processing
subroutines that lead to audio output.

An orchestra header statement operates once only, at orchestra setup time. It
is most commonly an assignment of some value to a global reserved symbol ,
e.g. sr = 20000. All orchestra header statements belong to a pseudo
instrument 0, an init pass of which is run prior to all other instruments at
score time 0. Any ordinary statement can serve as an orchestra header
statement, eg. gifreq = cpspch(8.09) provided it is an init-time only
operation.

An ordinary statement runs at either init time or performance time or both.
Operations which produce a result formally run at the rate of that result
(that is, at init time for i-rate results; at performance time for k- and
a-rate results), with the sole exception of the init opcode. Most generators
and modifiers, however, produce signals that depend not only on the
instantaneous value of their arguments but also on some preserved internal
state. These performance-time units therefore have an implicit init-time
component to set up that state. The run time of an operation which produces
no result is apparent in the opcode.

Arguments are values that are sent to an operation. Most arguments will
accept arithmetic expressions composed of constants, variables, reserved
symbols, value converters, arithmetic operations, and conditional values.

------------------------------------------------------------------------------
*orchkvar*
Constants and Variables	~

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

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

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

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

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

*variabletypes*

Table 1. Types of Variables

+-------------------------------------------------------------+
| Type                | When Renewable | Local    | Global    |
|---------------------+----------------+----------+-----------|
| reserved symbols    | permanent      | --       | r symbol  |
|---------------------+----------------+----------+-----------|
| score pfields       | i-time         | p number | --        |
|---------------------+----------------+----------+-----------|
| v-set symbols       | i-time         | v number | gv number |
|---------------------+----------------+----------+-----------|
| init variables      | i-time         | i name   | gi name   |
|---------------------+----------------+----------+-----------|
| MIDI controllers    | any time       | c number | --        |
|---------------------+----------------+----------+-----------|
| control signals     | p-time, k-rate | k name   | gk        |
|---------------------+----------------+----------+-----------|
| audio signals       | p-time, k-rate | a name   | ga name   |
|---------------------+----------------+----------+-----------|
| spectral data types | k-rate         | w name   | --        |
+-------------------------------------------------------------+

where rsymbol is a special reserved symbol (e.g. sr, kr), number is a
positive integer referring to a score pfield or sequence number, and name is
a string of letters and/or digits with local or global meaning. As might be
apparent, score parameters are local i-rate variables whose values are copied
from the invoking score statement just prior to the init pass through an
instrument, while MIDI controllers are variables which can be updated
asynchronously from a MIDI file or MIDI device.

------------------------------------------------------------------------------
*orchexpress*
Expressions	~

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

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

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

------------------------------------------------------------------------------
*orchheader*
Orchestra Header Statements	~

Statements that are normally placed in an orchestra header are |ctrlinit|
ctrlinit, |ftgen| ftgen, |kr| kr, |ksmps| ksmps, |massign| massign, |nchnls|
nchnls, |pgmassign| pgmassign, |pset| pset, |seed| seed, |sr| sr, and
|strset| strset.

------------------------------------------------------------------------------
*orchiblock*
Instrument Block Statements	~

Statements that define an instrument block are |endin| endin and |instr|
instr.

------------------------------------------------------------------------------
*orchvarinit*
Variable Initialization	~

Opcodes that let one initialize variables are |assign| assign, |divz| divz,
|init| init, and |tival| tival.

------------------------------------------------------------------------------
*controltop*
Instrument Control	~

------------------------------------------------------------------------------
*controlclockctl*
Clock Control	~

The opcodes to start and stop internal clocks are |clockoff| clockoff and
|clockon| clockon.

------------------------------------------------------------------------------
*controlconditional*
Conditional Values	~

The opcodes for conditional values are |equals| ==, |greaterequal| >=,
|greaterthan| >, |lessthan| <, |lessequal| <=, and |notequal| !=.

------------------------------------------------------------------------------
*controldurctl*
Duration Control Statements	~

The opcodes one can use to manipulate a note's duration are |ihold| ihold,
|turnoff| turnoff, and |turnon| turnon.

------------------------------------------------------------------------------
*controlfltkintro*
Introduction to FLTK Widgets and GUI controllers	~

Written by Gabriel Maldonado (http://csounds.com/maldonado)

Widgets allow the design of a custom Graphical User Interface to control an
orchestra in real-time. They are derived from the open-source library FLTK
(Fast Light Tool Kit). Such library is one of the fastest graphic libraries
available, supports OpenGL and should be source compatible with different
platforms (Windows, Linux, Unix and Mac OS). The subset of FLTK implemented
in Csound provides the following types of objects:

  * Containers

  * Valuators

  * Other widgets

Containers are widgets that contain other widgets such as panels, windows,
etc. Csound provides the following container objects:

  * Panels

  * Scroll areas

  * Pack

  * Tabs

  * Groups

The most useful objects are named valuators. These objects allow the user to
vary synthesis parameter values in real-time. Csound provides the following
valuator objects:

  * Sliders

  * Knobs

  * Rollers

  * Text fields

  * Joysticks

  * Counters

There are other widgets that are not valuators nor containers:

  * Buttons

  * Button banks

  * Labels

Also there are some other opcodes useful to modify the widget appearance:

  * Updating widget value.

  * Setting primary and selection colors of a widget.

  * Setting font type, size and color of widgets.

  * Resizing a widget.

  * Hiding and showing a widget.

At last, there are three important opcodes that allow the following actions:

  * Running the widget thread.

  * Loading snapshots containing the status of all valuators of an orchestra.

  * Saving snapshots containing the status of all valuators of an orchestra.

Here is an example preview of Csound code for a window containing a valuator.
Notice that all opcodes are init-rate and must be called only once per
session. The best way to use them is to place them in the header section of
an orchestra, externally to any instrument. Even though placing them inside
an instrument is not prohibited, unpredictable results can occur if that
instrument is called more than once.

Each container is made up of a couple of opcodes: the first indicating the
start of the container block and the last indicating the end of that
container block. Some container blocks can be nested but they must not be
crossed. After defining all containers, a widget thread must be run by using
the special FLrun opcode that takes no arguments.

Here is an example of creating a window:

 ;*******************************
 sr=48000
 kr=480
 ksmps=100
 nchnls=1

 ;*** It is recommended to put almost all GUI code in the
 ;*** header section of an orchestra

      FLpanel         "Panel1",450,550 ;***** start of container
 ; some widgets should contained here
      FLpanelEnd     ;***** end of container

      FLrun           ;***** runs the widget thread, it is always required!
 instr 1
 ;put some synthesis code here
 endin
 ;*******************************

The previous code simply creates a panel (an empty window because no widgets
are defined inside the container).

The following example creates two panels and inserts a slider inside each of
them:

 ;*******************************
 sr=48000
 kr=480
 ksmps=100
 nchnls=1

      FLpanel         "Panel1",450,550,100,100 ;***** start of container
 gk1,iha FLslider        "FLslider 1", 500, 1000, 2 ,1, ih1, 300,15, 20,50
      FLpanelEnd      ;***** end of container

      FLpanel         "Panel1",450,550,100,100 ;***** start of container
 gk2,ihb FLslider        "FLslider 2", 100, 200, 2 ,1, ih2, 300,15, 20,50
      FLpanelEnd      ;***** end of container

      FLrun           ;***** runs the widget thread, it is always required!
 instr 1
 ;put some synthesis code here
 ; gk1 and gk2 variables that contain the output of valuator
 ; widgets previously defined, can be used inside any instrument
 endin
 ;*******************************

All widget opcodes are init-rate opcodes, even if valuators output k-rate
variables. This happens because an independent thread is run based on a
callback mechanism. It consumes very few processing resources since there is
no need of polling. (This differs from other MIDI based controller opcodes.)
So you can use any number of windows and valuators without degrading the
real-time performance.

Since FLTK toolkit is still in evolution process, opcode syntax provided in
Csound could be modified in future version. This could cause some
incompatibilities between orchestras of a determinate version. However it
should not be hard to modify early orchestras in order to make them
compatible with later versions.

For more information, see the following sections.

------------------------------------------------------------------------------
*controlfltkcontainers*
FLTK Containers	~

The opcodes for FTLK containers are |flgroup| FLgroup, |flgroupend|
FLgroupEnd, |flpack| FLpack, |flpackend| FLpackEnd, |flpanel| FLpanel,
|flpanelend| FLpanelEnd, |flscroll| FLscroll, |flscrollend| FLscrollEnd,
|fltabs| FLtabs, and |fltabsend| FLtabsEnd.

------------------------------------------------------------------------------
*controlfltkvaluators*
FLTK Valuators	~

The opcodes for FLTK valuators are |flcount| FLcount, |fljoy| FLjoy, |flkeyb|
FLkeyb, |flknob| FLknob, |flroller| FLroller, |flslider| FLslider, and
|fltext| FLtext.

------------------------------------------------------------------------------
*controlfltkother*
Other FLTK Widgets	~

Other FLTK widget opcodes are |flbox| FLbox, |flbutbank| FLbutBank,
|flbutton| FLbutton, |flprintk| FLprintk, |flprintk2| FLprintk2, and
|flvalue| FLvalue,

------------------------------------------------------------------------------
*controlfltkappearance*
Modifying FLTK Widget Appearance	~

Opcodes one can use to modify FLTK widget appearance are |flcolor2| FLcolor2,
|flcolor| FLcolor, |flhide| FLhide, |fllabel| FLlabel, |flsetalign|
FLsetAlign, |flsetbox| FLsetBox, |flsetcolor2| FLsetColor2, |flsetcolor|
FLsetColor, |flsetfont| FLsetFont, |flsetposition| FLsetPosition, |flsetsize|
FLsetSize, |flsettext| FLsetText, |flsettextcolor| FLsetTextColor,
|flsettextsize| FLsetTextSize, |flsettexttype| FLsetTextType, |flsetval|
FLsetVal, |flsetvali| FLsetVal_i, and |flshow| FLshow.

------------------------------------------------------------------------------
*controlfltkgeneral*
General FLTK Widget-related Opcodes	~

The general FLTK widget-related opcodes are |flgetsnap| FLgetsnap,
|flloadsnap| FLloadsnap, |flrun| FLrun, |flsavesnap| FLsavesnap, |flsetsnap|
FLsetsnap, and |flupdate| FLupdate.

------------------------------------------------------------------------------
*controlfltksliderbank*
FLTK Slider Bank	~

The opcode for the FLTK slider bank is |flslidbnk| FLslidBnk.

------------------------------------------------------------------------------
*controlinvocat*
Instrument Invocation	~

The opcodes one can use to create score events from within a orchestra are
|event| event, |schedule| schedule, |schedwhen| schedwhen, and |schedkwhen|
schedkwhen.

------------------------------------------------------------------------------
*controlmacros*
Macros	~

The opcodes one can use to create, call, or undefine macros are |define|
#define, |dollar| $NAME, |include| #include, and |undef| #undef.

------------------------------------------------------------------------------
*controlpgmctl*
Program Flow Control	~

The opcodes to manipulate which orchestra statements are executed are
|cggoto| cggoto, |cigoto| cigoto, |ckgoto| ckgoto, |cngoto| cngoto, |elseif|
elseif, |else| else, |endif| endif, |goto| goto, |if| if, |igoto| igoto,
|kgoto| kgoto, |tigoto| tigoto, and |timout| timout.

------------------------------------------------------------------------------
*controlrealtime*
Real-time Performance Control	~

Opcodes that monitor and control real-time performance are |active| active,
|cpuprc| cpuprc, |maxalloc| maxalloc, and |prealloc| prealloc.

------------------------------------------------------------------------------
*controlreinitn*
Reinitialization	~

The opcodes that can generate another initialization phase are |reinit|
reinit, |rigoto| rigoto, and |rireturn| rireturn.

------------------------------------------------------------------------------
*controlsensing*
Sensing and Control	~

Opcodes that read from signals or on-screen controls are |button| button,
|checkbox| checkbox, |control| control, |follow| follow, |follow2| follow2,
|peak| peak, |pitch| pitch, |pitchamdf| pitchamdf, |sense| sense, |sensekey|
sensekey, |setctrl| setctrl, |tempest| tempest, |tempo| tempo, |tempoval|
tempoval, |seqtime| setime, |trigger| trigger, |trigseq| trigseq, and |xyin|
xyin.

------------------------------------------------------------------------------
*controlsubinstrument*
Sub-instrument Control	~

These opcodes let one define and use a sub-instrument: |ink| ink, |outk|
outk, and |subinstr| subinstr.

------------------------------------------------------------------------------
*controltimeread*
Time Reading	~

Opcodes one can use to read time values are |readclock| readclock, |rtclock|
rtclock, |timeinstk| timeinstk, |timeinsts| timeinsts, |timek| timek, and
|times| times.

------------------------------------------------------------------------------
*tabletop*
Function Table Control	~

------------------------------------------------------------------------------
*tablequeries*
Table Queries	~

Opcodes the query tables for information are |ftchnls| ftchnls, |ftlen|
ftlen, |ftlptim| ftlptim, |ftsr| ftsr, |nsamp| nsamp, and |tableng| tableng.

------------------------------------------------------------------------------
*tablereadwrit*
Read/Write Operations	~

Opcodes that read and write to a table are |ftloadk| ftloadk, |ftload|
ftload, |ftsavek| ftsavek, |ftsave| ftsave, |tablecopy| tablecopy, |tablegpw|
tablegpw, |tableicopy| tableicopy, |tableigpw| tableigpw, |tableimix|
tableimix, |tableiw| tableiw, |tablemix| tablemix, |tablera| tablera,
|tablew| tablew, |tablewa| tablewa, and |tablewkt| tablewkt.

------------------------------------------------------------------------------
*tableselect*
Table Selection	~

Opcodes that let one dynamically select tables are |tableikt| tableikt,
|tablekt| tablekt, and |tablexkt| tablexkt.

------------------------------------------------------------------------------
*mathtop*
Mathematical Operations	~

------------------------------------------------------------------------------
*mathamp*
Amplitude Converters	~

Opcodes to convert between different amplitude measurements are |ampdb|
ampdb, |ampdbfs| ampdbfs, |dbamp| dbamp, and |dbfsamp| dbfsamp.

------------------------------------------------------------------------------
*mathartlogic*
Arithmetic and Logic Operations	~

Opcodes that perform arithmetic and logic operations are |subtracts| -,
|adds| +, |opand| &&, |opor| ||, |multiplies| *, |divides| /, |raises| ^, and
|modulus| %.

------------------------------------------------------------------------------
*mathmatfunc*
Mathematical Functions	~

Opcodes that perform mathematical functions are |abs| abs, |exp| exp, |frac|
frac, |int| int, |log| log, |log10| log10, |logbtwo| logbtwo, |powoftwo|
powoftwo, and |sqrt| sqrt.

------------------------------------------------------------------------------
*mathopeqfunc*
Opcode Equivalents of Functions	~

Opcodes that perform the equivalent of mathematical functions are |mac| mac,
|maca| maca, |pow| pow, |product| product, and |sum| sum.

------------------------------------------------------------------------------
*mathrndfunc*
Random Functions	~

Opcodes that perform random functions are |birnd| birnd and |rnd| rnd.

------------------------------------------------------------------------------
*mathtrig*
Trigonometric Functions	~

Opcodes that perform trigonometric functions are |cos| cos, |cosh| cosh,
|cosinv| cosinv, |sin| sin, |sinh| sinh, |sininv| sininv, |tan| tan, |tanh|
tanh, |taninv| taninv, and |taninv2| taninv2.

------------------------------------------------------------------------------
*miditop*
MIDI Support	~

------------------------------------------------------------------------------
*midicontrol*
Controller Input	~

Opocodes that accept MIDI input are |aftouch| aftouch, |chanctrl| chanctrl,
|ctrl7| ctrl7, |ctrl14| ctrl14, |ctrl21| ctrl21, |initc7| initc7, |initc14|
initc14, |initc21| initc21, |midic7| midic7, |midic14| midic14, |midic21|
midic21, |midichannelaftertouch| midichannelaftertouch, |midichn| midichn,
|midicontrolchange| midicontrolchange, |mididefault| mididefault,
|midinoteoff| midinoteoff, |midinoteoncps| midinoteoncps, |midinoteonkey|
midinoteonkey, |midinoteonoct| midinoteonoct, |midinoteonpch| midinoteonpch,
|midipitchbend| midipitchbend, |midipolyaftertouch| midipolyaftertouch,
|midiprogramchange| midiprogramchange, and |polyaft| polyaft.

------------------------------------------------------------------------------
*midiconvert*
Converters	~

Opcodes that convert MIDI values are |ampmidi| ampmidi, |cpsmidi| cpsmidi,
|cpsmidib| cpsmidib, |cpstmid| cpstmid, |midictrl| midictrl, |notnum| notnum,
|octmidi| octmidi, |octmidib| octmidib, |pchbend| pchbend, |pchmidi| pchmidi,
|pchmidib| pchmidib, and |veloc| veloc.

------------------------------------------------------------------------------
*midiextender*
Event Extenders	~

Opcodes that let one extend the duration of an event are |release| release
and |xtratim| xtratim.

------------------------------------------------------------------------------
*midigeneric*
Generic Input and Output	~

Opcodes for generic MIDI input and output are |midiin| midiin and |midiout|
midiout.

------------------------------------------------------------------------------
*midionoff*
Note-on/Note-off	~

Opcodes to turn MIDI notes on or off are |midion| midion, |midion2| midion2,
|moscil| moscil, |noteoff| noteoff, |noteon| noteon, |noteondur| noteondur,
and |noteondur2| noteondur2.

------------------------------------------------------------------------------
*midioutput*
MIDI Message Output	~

Opcodes that send MIDI output are |mdelay| mdelay, |nrpn| nrpn, |outiat|
outiat, |outic| outic, |outic14| outic14, |outipat| outipat, |outipb| outipb,
|outipc| outipc, |outkat| outkat, |outkc| outkc, |outkc14| outkc14, |outkpat|
outkpat, |outkpb| outkpb, and |outkpc| outkpc.

------------------------------------------------------------------------------
*midirealtime*
Real-time Messages	~

Opcodes for real-time MIDI messages are |mclock| mclock and |mrtmsg| mrtmsg.

------------------------------------------------------------------------------
*midislidrbk*
Slider Banks	~

Opcodes for slider banks of MIDI controls are |s16b14| s16b14, |s32b14|
s32b14, |slider16| slider16, |slider16f| slider16f, |slider32| slider32,
|slider32f| slider32f, |slider64| slider64, |slider64f| slider64f, |slider8|
slider8, and |slider8f| slider8f.

------------------------------------------------------------------------------
*pitchtop*
Pitch Converters	~

------------------------------------------------------------------------------
*pitchfuncs*
Functions	~

Opcodes that provide common pitch functions are |cent| cent, |cpsoct| cpsoct,
|cpspch| cpspch, |db| db, |octave| octave, |octcps| octcps, |octpch| octpch,
|pchoct| pchoct, and |semitone| semitone.

------------------------------------------------------------------------------
*pitchtuning*
Tuning Opcodes	~

Opcodes that provide tuning functions are |cps2pch| cps2pch, |cpsxpch|
cpsxpch, |cpstun| cpstun, and |cpstuni| cpstuni.

------------------------------------------------------------------------------
*siggentop*
Signal Generators	~

------------------------------------------------------------------------------
*siggenadditive*
Additive Synthesis/Resynthesis	~

The opcodes for additive synthesis and resynthesis are |adsyn| adsyn,
|adsynt| adsynt, and |hsboscil| hsboscil.

------------------------------------------------------------------------------
*siggenbasic*
Basic Oscillators	~

The basic oscillator opcodes are |lfo| lfo, |oscbnk| oscbnk, |oscil| oscil,
|oscil3| oscil3, |oscili| oscili, |oscils| oscils, |poscil| poscil, and
|poscil3| poscil3.

------------------------------------------------------------------------------
*siggendynamic*
Dynamic Spectrum Oscillators	~

The opcodes that generate dynamic spectra are |buzz| buzz, |gbuzz| gbuzz,
|mpulse| mpulse, and |vco| vco.

------------------------------------------------------------------------------
*siggenfmsynth*
FM Synthesis	~

The FM synthesis opcodes are |fmb3| fmb3, |fmbell| fmbell, |fmmetal| fmmetal,
|fmpercfl| fmpercfl, |fmrhode| fmrhode, |fmvoice| fmvoice, |fmwurlie|
fmwurlie, |foscil| foscil, and |foscili| foscili,

------------------------------------------------------------------------------
*siggengranular*
Granular Synthesis	~

The granular synthesis opcodes are |fof| fof, |fof2| fof2, |fog| fog, |grain|
grain, |grain2| grain2, |grain3| grain3, |granule| granule, |sndwarp|
sndwarp, and |sndwarpst| sndwarpst.

------------------------------------------------------------------------------
*siggenlineexp*
Linear and Exponential Generators	~

The opcodes that generate linear or exponential curves or segments are |adsr|
adsr, |expon| expon, |expseg| expseg, |expsega| expsega, |expsegr| expsegr,
|jspline| jspline, |line| line, |linseg| linseg, |linsegr| linsegr, |loopseg|
loopseg, |lpshold| lpshold, |madsr| madsr, |mxadsr| mxadsr, |rspline|
rspline, |transeg| transeg, and |xadsr| xadsr.

------------------------------------------------------------------------------
*siggenlpcresyn*
Linear Predictive Coding (LPC) Resynthesis	~

The linear predictive coding resynthesis opcodes are |lpfreson| lpfreson,
|lpinterp| lpinterp, |lpread| lpread, |lpreson| lpreson, and |lpslot| lpslot.

------------------------------------------------------------------------------
*siggenmodels*
Models and Emulations	~

The opcodes that model or emulate the sounds of other instruments are
|bamboo| bamboo, |cabasa| cabasa, |crunch| crunch, |dripwater| dripwater,
|gogobel| gogobel, |guiro| guiro, |lorenz| lorenz, |mandol| mandol, |marimba|
marimba, |moog| moog, |planet| planet, |sandpaper| sandpaper, |sekere|
sekere, |shaker| shaker, |sleighbells| sleighbells, |stix| stix, |tambourine|
tambourine, |vibes| vibes, and |voice| voice.

------------------------------------------------------------------------------
*siggenphasors*
Phasors	~

The opcodes that generate a moving phase value |phasor| phasor and
|phasorbnk| phasorbnk.

------------------------------------------------------------------------------
*siggennoise*
Random (Noise) Generators	~

Opcodes that generate random numbers are |betarand| betarnd, |bexprnd|
bexprnd, |cauchy| cauchy, |cuserrnd| cuserrnd, |duserrnd| duserrnd, |exprand|
exprand, |gauss| gauss, |linrand| linrand, |noise| noise, |pcauchy| pcauchy,
|pinkish| pinkish, |poisson| poisson, |rand| rand, |randh| randh, |randi|
randi, |rnd31| rnd31, |random| rand, |randomh| randomh, |randomi| randomi,
|trirand| trirand, |unirand| unirand, |urd| urd, and |weibull| weibull.

------------------------------------------------------------------------------
*siggensample*
Sample Playback	~

Opcodes that implement sample playback are |bbcutm| bbcutm, |bbcuts| bbcuts,
|loscil| loscil, |loscil3| loscil3, |lphasor| lphasor, |lposcil| lposcil,
|lposcil3| lposcil3, |sfilist| sfilist, |sfinstr| sfinstr, |sfinstr3|
sfinstr3, |sfinstr3m| sfinstr3m, |sfinstrm| sfinstrm, |sfload| sfload,
|sfpassign| sfpassign, |sfplay| sfplay, |sfplay3| sfplay3, |sfplay3m|
sfplay3m, |sfplaym| sfplaym, |sfplist| sfplist, |sfpreset| sfpreset, and
|waveset| waveset.

------------------------------------------------------------------------------
*siggenscantop*
Scanned Synthesis	~

Scanned synthesis is a variant of physical modeling, where a network of
masses connected by springs is used to generate a dynamic waveform. The
opcode |scanu| scanu defines the mass/spring network and sets it in motion.
The opcode |scans| scans follows a predefined path (trajectory) around the
network and outputs the detected waveform. Several scans instances may follow
different paths around the same network.

These are highly efficient mechanical modelling algorithms for both synthesis
and sonic animation via algorithmic processing. They should run in real-time.
Thus, the output is useful either directly as audio, or as controller values
for other parameters.

The Csound implementation adds support for a scanning path or matrix.
Essentially, this offers the possibility of reconnecting the masses in
different orders, causing the signal to propagate quite differently. They do
not necessarily need to be connected to their direct neighbors. Essentially,
the matrix has the effect of "molding" this surface into a radically
different shape.

To produce the matrices, the table format is straightforward. For example,
for 4 masses we have the following grid describing the possible connections:

+-------------------+
|   | 1 | 2 | 3 | 4 |
|---+---+---+---+---|
| 1 |   |   |   |   |
|---+---+---+---+---|
| 2 |   |   |   |   |
|---+---+---+---+---|
| 3 |   |   |   |   |
|---+---+---+---+---|
| 4 |   |   |   |   |
+-------------------+

Whenever two masses are connected, the point they define is 1. If two masses
are not connected, then the point they define is 0. For example, a
unidirectional string has the following connections: (1,2), (2,3), (3,4). If
it is bidirectional, it also has (2,1), (3,2), (4,3)). For the unidirectional
string, the matrix appears:

+-------------------+
|   | 1 | 2 | 3 | 4 |
|---+---+---+---+---|
| 1 | 0 | 1 | 0 | 0 |
|---+---+---+---+---|
| 2 | 0 | 0 | 1 | 0 |
|---+---+---+---+---|
| 3 | 0 | 0 | 0 | 1 |
|---+---+---+---+---|
| 4 | 0 | 0 | 0 | 0 |
+-------------------+

The above table format of the connection matrix is for conceptual convenience
only. The actual values shown in te table are obtained by scans from an ASCII
file using |gen23| GEN23. The actual ASCII file is created from the table
model row by row. Therefore the ASCII file for the example table shown above
becomes:

0100001000010000

This matrix example is very small and simple. In practice, most scanned
synthesis instruments will use many more masses than four, so their matrices
will be much larger and more complex. See the example in the |scans| scans
documentation.

Please note that the generated dynamic wavetables are very unstable. Certain
values for masses, centering, and damping can cause the system to "blow up"
and the most interesting sounds to emerge from your loudspeakers!

The supplement to this manual contains a tutorial on scanned synthesis. The
tutorial, examples, and other information on scanned synthesis is available
from the Scanned Synthesis page at cSounds.com.

Scanned synthesis developed by Bill Verplank, Max Mathews and Rob Shaw at
Interval Research between 1998 and 2000.

Opcodes that implement scanned synthesis are |scanhammer| scanhammer, |scans|
scans, |scantable| scantable, |scanu| scanu, |xscanmap| xscanmap, |xscans|
xscans, and |xscanu| xscanu.

------------------------------------------------------------------------------
*siggenstft*
Short-time Fourier Transform (STFT) Resynthesis	~

  Use of PVOC-EX files with the old Csound pvoc opcodes                       
  All the original pvoc opcodes can now read a PVOC-EX file, as well as the   
  native non-portable file format. As the PVOC-EX file uses a double-size     
  analysis window, users may find that this gives a useful improvement in     
  quality, for some sounds and processes, despite the fact that the           
  resynthesis does not use the same window size.                              
  Apart from the window size parameter, the main difference between the       
  original .pv format and PVOC-EX is in the amplitude range of analysis       
  frames. While rescaling is applied, so that no significant difference in    
  output level is experienced, whichever file format is used, some slight     
  loss of amplitude can still arise, as the double window usage itself        
  modifies frame amplitudes, of which the resynthesis code is unaware. Note   
  that all the original pvoc opcodes expect a mono analysis file, and         
  multi-channel PVOC-EX files will accordingly be rejected.                   

Opcodes the implement STFT resynthesis are |ktableseg| ktableseg, |pvadd|
pvadd, |pvbufread| pvbufread, |pvcross| pvcross, |pvinterp| pvinterp, |pvoc|
pvoc, |pvread| pvread, |tableseg| tableseg, |tablexseg| tablexseg, and
|vpvoc| vpvoc.

------------------------------------------------------------------------------
*siggentableacc*
Table Access	~

The opcodes that access tables are |oscil1| oscil1, |oscil1i| oscil1i,
|osciln| osciln, |oscilx| oscilx, |table| table, |table3| table3, and
|tablei| tablei.

------------------------------------------------------------------------------
*siggenwaveterr*
Wave Terrain Synthesis	~

The opcode that uses wave terrain synthesis is |wterrain| wterrain.

------------------------------------------------------------------------------
*siggenwavguide*
Waveguide Physical Modeling	~

The opcodes that implement waveguide physical modeling are |pluck| pluck,
|repluck| repluck, |wgbow| wgbow, |wgbowedbar| wgbowedbar, |wgbrass| wgbrass,
|wgclar| wgclar, |wgflute| wgflute, |wgpluck| wgpluck, and |wgpluck2|
wgpluck2.

------------------------------------------------------------------------------
*sigiotop*
Signal Input and Output	~

------------------------------------------------------------------------------
*sigiofileio*
File Input and Output	~

The opcodes for file input and output are |clear| clear, |dumpk| dumpk,
|dumpk2| dumpk2, |dumpk3| dumpk3, |dumpk4| dumpk4, |fiopen| fiopen, |fin|
fin, |fini| fini, |fink| fink, |fout| fout, |fouti| fouti, |foutir| foutir,
|foutk| foutk, |readk| readk, |readk2| readk2, |readk3| readk3, |readk4|
readk4, and |vincr| vincr.

------------------------------------------------------------------------------
*sigioinput*
Input	~

The opcodes that receive audio signals are: |diskin| diskin, |in| in, |in32|
in32, |inch| inch, |inh| inh, |ino| ino, |inq| inq, |ins| ins, |invalue|
invalue, |inx| inx, |inz| inz, and |soundin| soundin.

------------------------------------------------------------------------------
*sigiooutput*
Output	~

The opcodes that write audio signals are: |out| out, |out32| out32, |outc|
outc, |outch| outch, |outh| outh, |outo| outo, |outq| outq, |outq1| outq1,
|outq2| outq2, |outq3| outq3, |outq4| outq4, |outs| outs, |outs1| outs1,
|outs2| outs2, |outvalue| outvalue, |outx| outx, |outz| outz, and |soundout|
soundout.

------------------------------------------------------------------------------
*sigiopdisplay*
Printing and Display	~

Opcodes for printing and displaying values are |dispfft| dispfft, |display|
display, |flashtxt| flashtxt, |print| print, |printk| printk, |printk2|
printk2, and |printks| printks.

------------------------------------------------------------------------------
*sigioqueries*
Sound File Queries	~

The opcodes that query information about files are |filelen| filelen,
|filenchnls| filenchnls, |filepeak| filepeak, and |filesr| filesr.

------------------------------------------------------------------------------
*sigmodtop*
Signal Modifiers	~

------------------------------------------------------------------------------
*sigmodampmod*
Amplitude Modifiers	~

The opcodes that modify amplitude are |balance| balance, |clip| clip, |dam|
dam, |gain| gain, and |rms| rms.

------------------------------------------------------------------------------
*sigmodconmorph*
Convolution and Morphing	~

The opcodes that convolve and morph signals are |convle| convle, |convolve|
convolve, |cross2| cross2, |dconv| dconv, and |ftmorf| ftmorf.

------------------------------------------------------------------------------
*sigmoddelay*
Delay	~

The opcodes that implement delay are |delay| delay, |delay1| delay1, |delayr|
delayr, |delayw| delayw, |deltap| deltap, |deltap3| deltap3, |deltapi|
deltapi, |deltapn| deltapn, |deltapx| deltapx, |deltapxw| deltapw, |multitap|
multitap, |vdelay| vdelay, |vdelay3| vdelay3, |vdelayx| vdelayx, |vdelayxs|
vdelayxs, |vdelayxq| vdelayxq, |vdelayxw| vdelayxw, |vdelayxwq| vdelayxwq,
and |vdelayxws| vdelayxws.

------------------------------------------------------------------------------
*sigmodenvelope*
Envelope Modifiers	~

The opcodes that modify envelopes are |envlpx| envlpx, |envlpxr| envlpxr,
|linen| linen, and |linenr| linenr.

------------------------------------------------------------------------------
*sigmodpanspatl*
Panning and Spatialization	~

The opcodes that one can use for panning and spatialization are |hrtfer|
hrtfer, |locsend| locsend, |locsig| locsig, |pan| pan, |space| space,
|spat3d| spat3d, |spat3di| spat3di, |spat3dt| spat3dt, |spdist| spdist,
|spsend| spsend, |vbap16| vbap16, |vbap16move| vbap16move, |vbap4| vbap4,
|vbap4move| vbap4move, |vbap8| vbap8, |vbap8move| vbap8move, |vbaplsinit|
vbaplsinit, |vbapz| vbapz, and |vbapzmove| vbapzmove.

------------------------------------------------------------------------------
*sigmodreverbtn*
Reverberation	~

The opcodes one can use for reverberation are |alpass| alpass, |babo| babo,
|comb| comb, |nestedap| nestedap, |nreverb| nreverb, |reverb2| reverb2,
|reverb| reverb, |valpass| valpass, and |vcomb| vcomb

------------------------------------------------------------------------------
*sigmodsample*
Sample Level Operators	~

The opcodes one may use to modify signals are |opa| a, |diff| diff,
|downsamp| downsamp, |fold| fold, |opi| i, |integ| integ, |interp| interp,
|ntrpol| ntrpol, |samphold| samphold, and |upsamp| upsamp.

------------------------------------------------------------------------------
*sigmodsiglimit*
Signal Limiters	~

Opcodes that one can use to limit signals are |limit| limit, |mirror| mirror,
and |wrap| wrap.

------------------------------------------------------------------------------
*sigmodspeciale*
Special Effects	~

Opcodes that generate special effects are |distort1| distort1, |flanger|
flanger, |harmon| harmon, |jitter| jitter, |jitter2| jitter2, |phaser1|
phaser1, |phaser2| phaser2, |vibr| vibr, and |vibrato| vibrato.

------------------------------------------------------------------------------
*sigmodspeciali*
Specialized Filters	~

The opcodes that recreate specialized filters are |dcblock| dcblock, |nlfilt|
nlfilt, and |pareq| pareq.

------------------------------------------------------------------------------
*sigmodstandard*
Standard Filters	~

The opcodes for standard filters are |areson| areson, |aresonk| aresonk,
|atone| atone, |atonek| atonek, |atonex| atonex, |biquad| biquad, |biquada|
biquada, |butbp| butbp, |butbr| butbr, |buthp| buthp, |butlp| butlp,
|butterbp| butterbp, |butterbr| butterbr, |butterhp| butterhp, |butterlp|
butterlp, |clfilt| clfilt, |filter2| filter2, |hilbert| hilbert, |lineto|
lineto, |lowpass2| lowpass2, |lowres| lowres, |lowresx| lowresx, |lpf18|
lpf18, |moogvcf| moogvcf, |port| port, |portk| portk, |reson| reson, |resonk|
resonk, |resonr| resonr, |resonx| resonx, |resony| resony, |resonz| resonz,
|rezzy| rezzy, |svfilter| svfilter, |tbvcf| tbvcf, |tlineto| tlineto, |tone|
tone, |tonek| tonek, |tonex| tonex, |vlowres| vlowres, and |zfilter2|
zfilter.

------------------------------------------------------------------------------
*sigmodwavguide*
Waveguides	~

The opcodes that use waveguides to modify a signal are |streson| streson,
|wguide1| wguide1, and |wguide2| wguide2.

------------------------------------------------------------------------------
*spectraltop*
Spectral Processing	~

------------------------------------------------------------------------------
*spectralnonstand*
Non-standard Spectral Processing	~

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

The opcodes for non-standard spectral processing are |specaddm| specaddm,
|specdiff| specdiff, |specdisp| specdisp, |specfilt| specfilt, |spechist|
spechist, |specptrk| specptrk, |specscal| specscal, |specsum| specsum, and
|spectrum| spectrum.

------------------------------------------------------------------------------
*spectralrealtime*
Tools for Real-time Spectral Processing	~

With these opcodes, two new core facilities are added to Csound. They offer
improved audio quality, and fast performance, enabling high-quality analysis
and resynthesis (together with transformations) to be applied in real-time to
live signals. The original Csound phase vocoder remains unaltered; the new
opcodes use an entirely separate set of functions based on "pvoc.c" in the
CARL distribution, written by Mark Dolson.

The Csound |dnoise| dnoise and |srconv| srconv utilities (also by Dolson,
from CARL) also use this pvoc engine. CARL pvoc is also the basis for the
phase vocoder included in the Composer's Desktop Project. A few small but
important modifications have been made to the original CARL code to support
real-time streaming.

 1. Support for the new PVOC-EX analysis file format. This is a fully
    portable (cross-platform) open file format, supporting three analysis
    formats, and multi-channel signals. Currently only the standard
    amplitude+frequency format has been implemented in the opcodes, but the
    file format itself supports amplitude+phase and complex (real-imaginary)
    formats. In addition to the new opcodes, the original Csound pvoc opcodes
    have been extended (and thereby with enhanced audio quality in some
    cases) to read PVOC-EX files as well as the original (non-portable)
    format.

    Full details of the structure of a PVOC-EX file are available via the
    website:
    http://www.bath.ac.uk/~masjpf/NCD/researchdev/pvocex/pvocex.html. This
    site also gives details of the freely available console programs pvocex
    and pvocex2 which can be used to create PVOC-EX files in all supported
    formats.

 2. A new frequency-domain signal type, fully streamable, with f as the
    leading character. In this document it is conveniently referred to as an
    fsig. Primary support for fsigs is provided by the opcodes pvsanal and
    pvsynth, which perform conventional phase vocoder overlap-add analysis
    and resynthesis, independently of the orchestra control-rate. The only
    requirement is that the control-rate kr be higher than or equal to the
    analysis rate, whch can be expressed by the requirement that ksmps <=
    overlap, where overlap is the distance in samples between analysis
    frames, as specified for pvsanal. As overlap is typically at least 128,
    and more usually 256, this is not an onerous restriction in practice. The
    opcode pvsinfo can be used at init time to acquire the properties of an
    fsig.

    The fsig enables the nominal separation between the analysis and
    resynthesis stages of the phase vocoder to be exposed to the Csound
    programmer, so that not only can alternatives be employed for either or
    both of these stages (not only oscillator-bank resynthesis, but also the
    generation of synthetic fsig streams), but opcodes, operating on the fsig
    stream, can themselves become more elemental. Thus the fsig enables the
    creation of a true streaming plugin framework for frequency domain
    signals. With the old pvoc opcodes, each opcode is required to act as a
    resynthesiser, so that facilities such as pitch scaling are duplicated in
    each opcode; and in many cases the opcodes are parameter-rich. The
    separation of analysis and synthesis stages by means of the fsig
    encourages the development of a wide range of simple building-block
    opcodes implementing one or two functions, with which more elaborate
    processes can be constructed.

This is very much a preliminary and experimental release, and it is possible
that the precise definition of the opcodes may change, in response to user
feedback. Also, clearly, many new possibilities for opcodes are opened up;
these factors may also have a retrospective influence on the opcodes
presented here.

Note that some opcode parameters currently have restricted or missing
implementation. This is at least in part in order to keep the opcodes simple
at this stage, and also because they highlight important design issues on
which no decision has yet been made, and on which opinions from users are
sought.

One important point about the new signal type is that because the analysis
rate is typically much lower than kr, new analysis frames are not available
on each k-cycle. Internally, the opcodes track ksmps, and also maintain a
frame counter, so that frames are read and written at the correct times; this
process is generally transparent to the user. However, it means that k-rate
signals only act on an fsig at the analysis rate, not at each k-cycle. The
opocde pvsftw returns a k-rate flag that is set when new fsig data is valid.

Because of the nature of the overlap-add system, the use of these opcodes
incurs a small but significant delay, or latency, determined by the window
size (max(ifftsize,iwinsize)). This is typically around 23msecs. In this
first release, the delay is slightly in excess of the theoretical minimum,
and it is hoped that it can be reduced, as the opcodes are further optimized
for real-time streaming.

The opcodes for real-time spectral processing are |pvsadsyn| pvsadsyn,
|pvsanal| pvsanal, |pvscross| pvscross, |pvsfread| pvsfread, |pvsftr| pvsftr,
|pvsftw| pvsftw, |pvsinfo| pvsinfo, |pvsmaska| pvsmaska, and |pvsynth|
pvsynth.

------------------------------------------------------------------------------
*zaktop*
Zak Patch System	~

The zak opcodes are used to create a system for i-rate, k-rate or a-rate
patching. The zak system can be thought of as a global array of variables.
These opcodes are useful for performing flexible patching or routing from one
instrument to another. The system is similar to a patching matrix on a mixing
console or to a modulation matrix on a synthesizer. It is also useful
whenever an array of variables is required.

The zak system is initialized by the |zakinit| zakinit opcode, which is
usually placed just after the other global initializations: sr, kr, ksmps,
nchnls. The zakinit opcode defines two areas of memory, one area for i- and
k-rate patching, and the other area for a-rate patching. The zakinit opcode
may only be called once. Once the zak space is initialized, other zak opcodes
can be used to read from, and write to the zak memory space, as well as
perform various other tasks.

Opcodes for the zak patch system are |zacl| zacl, |zakinit| zakinit, |zamod|
zamod, |zar| zar, |zarg| zarg, |zaw| zaw, |zawm| zawm, |zir| zir, |ziw| ziw,
|ziwm| ziwm, |zkcl| zkcl, |zkmod| zkmod, |zkr| zkr, |zkw| zkw, and |zkwm|
zkwm.

------------------------------------------------------------------------------
*scoretop*
The Standard Numeric Score	~

------------------------------------------------------------------------------
*scorepreproc*
Preprocessing of Standard Scores	~

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

------------------------------------------------------------------------------
*scorecarry*
Carry	~

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

Three additional features are available for p2 alone: +, ^ + x, and ^ - x.
The symbol + in p2 will be given the value of p2 + p3 from the preceding i
statement. This enables note action times to be automatically determined from
the sum of preceding durations. The + symbol can itself be carried. It is
legal only in p2. E.g.: the statements

 i1   0    .5        100        
 i .  +                  
 i

will result in

 i1   0         .5        100
 i1   .5        .5        100
 i1   1         .5        100

The symbols ^ + x and ^ - x determine the current p2 by adding or
subtracting, respectively, the value of x from the preceding p2. These may be
used in p2 only.

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

------------------------------------------------------------------------------
*scoretempo*
Tempo	~

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

------------------------------------------------------------------------------
*scoresort*
Sort	~

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

------------------------------------------------------------------------------
*scorenb*
N.B.	~

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

------------------------------------------------------------------------------
*scorenextp*
Next-P and Previous-P Symbols	~

At the close of any of the operations |scorecarry| Carry, |scoretempo| Tempo,
and |scoresort| Sort, three additional score features are interpreted during
file writeout: next-p, previous-p, and ramping.

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

E.g.: the statements

 i1   0    1    10   np4  pp5
 i1   1    1    20
 i1   1    1    30

will result in

i1   0    1    10   20   0
i1   1    1    20   30   20
i1   2    1    30   0    30

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

------------------------------------------------------------------------------
*scoreramping*
Ramping	~

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

 i1   0    1    100
 i1   1    1    <
 i1   2    1    <
 i1   3    1    400
 i1   4    1    <
 i1   5    1    0

will result in

 i1   0    1    100
 i1   1    1    200
 i1   2    1    300
 i1   3    1    400
 i1   4    1    200
 i1   5    1    0

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

Starting with Csound version 3.52, using the symbols ( or ) will result in an
exponential interpolation ramp, similar to expon. The symbols { and } to
define an exponential ramp have been deprecated. Using the symbol ~ will
result in uniform, random distribution between the first and last values of
the ramp. Use of these functions must follow the same rules as the linear
ramp function.

------------------------------------------------------------------------------
*scoremacros*
Score Macros	~

Description		~

Macros are textual replacements which are made in the score as it is being
presented to the system. The macro system in Csound is a very simple one, and
uses the characters # and $ to define and call macros. This can can allow for
simpler score writing, and provide an elementary alternative to full score
generation systems.The score macro system is similar to, but independent of,
the macro system in the orchestra language.

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

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

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

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

Syntax		~

#define NAME # replacement text #

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

$NAME.

#undef NAME

Initialization		~

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

Performance		~

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

Another Use For Macros. When writing a complex score it is sometimes all too
easy to forget to what the various instrument numbers refer. One can use
macros to give names to the numbers. For example

 #define Flute  #i1#
 #define Whoop  #i2#

 $Flute.  0  10  4000  440
 $Whoop.  5  1

Examples		~

Example 1. Simple Macro

A note-event has a set of p-fields which are repeated:

 #define ARGS # 1.01 2.33 138#
 i1 0 1 8.00  1000 $ARGS
 i1 0 1 8.01  1500 $ARGS
 i1 0 1 8.02  1200 $ARGS
 i1 0 1 8.03  1000 $ARGS

This will get expanded before sorting into:

 i1 0 1 8.00  1000 1.01 2.33 138
 i1 0 1 8.01  1500 1.01 2.33 138
 i1 0 1 8.02  1200 1.01 2.33 138
 i1 0 1 8.03  1000 1.01 2.33 138

This can save typing, and is makes revisions easier. If there were two sets
of p-fields one could have a second macro (there is no real limit on the
number of macros one can define).

 #define ARGS1 # 1.01 2.33 138#
 #define ARGS2 # 1.41 10.33 1.00#
 i1 0 1 8.00  1000 $ARGS1
 i1 0 1 8.01  1500 $ARGS2
 i1 0 1 8.02  1200 $ARGS1
 i1 0 1 8.03  1000 $ARGS2

Example 2. Macros with arguments

 #define ARG(A) # 2.345   1.03   $A   234.9#
 i1 0 1 8.00 1000 $ARG(2.0)
 i1  + 1 8.01 1200 $ARG(3.0)

which expands to

 i1 0 1 8.00 1000 2.345   1.03   2.0   234.9
 i1  + 1 8.01 1200 2.345   1.03   3.0   234.9

Credits		~

Author: John ffitch

University of Bath/Codemist Ltd.

Bath, UK

April, 1998 (New in Csound version 3.48)

------------------------------------------------------------------------------
*mult*
Multiple File Score	~

Description		~

Using the score in more than one file.

Syntax		~

#include "filename"

Performance		~

It is sometimes convenient to have the score in more than one file. This use
is supported by the #include facility which is part of the macro system. A
line containing the text

 #include "filename"

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

This takes input from the named file until it ends, when input reverts to the
previous input. There is currently a limit of 20 on the depth of included
files and macros.

A suggested use of #include would be to define a set of macros which are part
of the composer's style. It could also be used to provide repeated sections.

 s
 #include :section1:
 ;; Repeat that
 s
 #include :section1:

Alternative methods of doing repeats, use the |r| r statement, |m| m
statement, and |n| n statement.

Credits		~

Author: John ffitch

University of Bath/Codemist Ltd.

Bath, UK

April, 1998 (New in Csound version 3.48)

Thanks to Luis Jure for pointing out the incorrect syntax in multiple file
include statement.

------------------------------------------------------------------------------
*scoreeval*
Evaluation of Expressions	~

In earlier versions of Csound the numbers presented in a score were used as
given. There are occasions when some simple evaluation would be easier. This
need is increased when there are macros. To assist in this area the syntax of
an arithmetic expressions within square brackets [ ] has been introduced.
Expressions built from the operations +, -, *, /, %, and ^ are allowed,
together with grouping with ( ). The expressions can include numbers, and
naturally macros whose values are numeric or arithmetic strings. All
calculations are made in floating point numbers. Note that unary minus is not
yet supported.

New in Csound version 3.56 are @x (next power-of-two greater than or equal to
x) and @@x (next power-of-two-plus-one greater than or equal to x).

Example

 r3  CNT

 i1  0  [0.3*$CNT.]
 i1  +  [($CNT./3)+0.2]

 e

As the three copies of the section have the macro $CNT. with the different
values of 1, 2 and 3, this expands to

 s
 i1  0  0.3
 i1  0.3  0.533333
 s
 i1  0  0.6
 i1  0.6  0.866667
 s
 i1  0  0.9
 i1  0.9  1.2
 e

This is an extreme form, but the evaluation system can be used to ensure that
repeated sections are subtly different.

Credits		~

Author: John ffitch

University of Bath/Codemist Ltd.

Bath, UK

April, 1998 (New in Csound version 3.48)

------------------------------------------------------------------------------
*scorestatements*
Score Statements	~

The statements used in scores are |a| a, |b| b, |e| e, |f| f, |i| i, |m| m,
|n| n, |r| r, |s| s, |t| t, |v| v, and |x| x.

------------------------------------------------------------------------------
*scoresinegen*
Sine/Cosine Generators	~

The GEN routines that generate sine or cosine values are |gen09| GEN09,
|gen10| GEN10, |gen11| GEN11, |gen19| GEN19, |gen30| GEN30, |gen33| GEN33,
and |gen34| GEN34.

------------------------------------------------------------------------------
*scoreseggen*
Line/Exponential Segment Generators	~

GEN routines that generate tables with linear or exponential segments are
|gen05| GEN05, |gen06| GEN06, |gen07| GEN07, |gen08| GEN08, |gen16| GEN16,
|gen25| GEN25, and |gen27| GEN27.

------------------------------------------------------------------------------
*scorefilegen*
File Access GEN Routines	~

The GEN routines that access files are |gen01| GEN01, |gen23| GEN23, and
|gen28| GEN28.

------------------------------------------------------------------------------
*scorenumgen*
Numeric Value Access GEN Routines	~

The GEN routines that generate tables from numeric values are |gen02| GEN02
and |gen17| GEN17.

------------------------------------------------------------------------------
*scorewingen*
Window Function GEN Routines	~

The GEN routine for window functions is |gen20| GEN20.

------------------------------------------------------------------------------
*scorerandgen*
Random Function GEN Routines	~

GEN routines the generate random distributions are |gen21| GEN21, |gen40|
GEN40, |gen41| GEN41, and |gen42| GEN42.

------------------------------------------------------------------------------
*scorewavegen*
Waveshaping GEN Routines	~

The GEN routines that have waveshaping functionality are |gen03| GEN03,
|gen13| GEN13, |gen14| GEN14, and |gen15| GEN15.

------------------------------------------------------------------------------
*scoreampgen*
Amplitude Scaling GEN Routines	~

GEN routines that perform amplitude scaling are |gen04| GEN04, |gen12| GEN12,
and |gen24| GEN24.

------------------------------------------------------------------------------
*scoremixgen*
Mixing GEN Routines	~

GEN routines that mix together waverforms are |gen18| GEN18, |gen31| GEN31,
and |gen32| GEN32.

*partreference*

                                II. Reference

Table of Contents

|opcodestop| Orchestra Opcodes and Operators

|scoregenstop| Score Statements and GEN Routines

|utilitytop| The Utility Programs

|cscoretop| Cscore

|addmodtop| Adding your own Cmodules to Csound

------------------------------------------------------------------------------
*opcodestop*
Orchestra Opcodes and Operators	~

------------------------------------------------------------------------------
*notequal*
!=	~

!= --  Determines if one value is not equal to another.

Description		~

Determines if one value is not equal to another.

Syntax		~

(a != b ? v1 : v2)

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

Performance		~

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

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

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

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

Examples		~

Here is an example of the != opcode. It uses the files notequal.orc and
notequal.sco.

Example 1. Example of the != opcode.

 /* notequal.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 44100
 ksmps = 1
 nchnls = 1

 ; Instrument #1.
 instr 1
; Get the 4th p-field from the score.
k1 =  p4

; Is it not equal to 3? (1 = true, 0 = false)
k2 = (p4 != 3 ? 1 : 0)

; Print the values of k1 and k2.
printks "k1 = %f, k2 = %f\\n", 1, k1, k2
 endin
 /* notequal.orc */

 /* notequal.sco */
 /* Written by Kevin Conder */
 ; Call Instrument #1 with a p4 = 2.
 i 1 0 0.5 2
 ; Call Instrument #1 with a p4 = 3.
 i 1 1 0.5 3
 ; Call Instrument #1 with a p4 = 4.
 i 1 2 0.5 4
 e
 /* notequal.sco */

Its output should include lines like this:

 k1 = 2.000000, k2 = 1.000000
 k1 = 3.000000, k2 = 0.000000
 k1 = 4.000000, k2 = 1.000000

See Also		~

|equals| ==, |greaterequal| >=, |greaterthan| >, |lessequal| <=, |lessthan| <

------------------------------------------------------------------------------
*define*
#define	~

#define --  Defines a macro.

Description		~

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

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

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

Syntax		~

#define NAME # replacement text #

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

Initialization		~

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

Performance		~

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

Examples		~

Here is a simple example of the defining a macro. It uses the files
define.orc and define.sco.

Example 1. Simple example of the define macro.

 /* define.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Define the macros.
 #define VOLUME #5000#
 #define FREQ #440#
 #define TABLE #1#

 ; Instrument #1
 instr 1
; Use the macros.
; This will be expanded to "a1 oscil 5000, 440, 1".
a1 oscil $VOLUME, $FREQ, $TABLE

; Send it to the output.
out a1
 endin
 /* define.orc */

 /* define.sco */
 /* Written by Kevin Conder */
 ; Define Table #1 with an ordinary sine wave.
 f 1 0 32768 10 1
 ; Play Instrument #1 for two seconds.
 i 1 0 2
 e
 /* define.sco */

Its output should include lines like this:

 Macro definition for VOLUME
 Macro definition for CPS
 Macro definition for TABLE

Here is an example of the defining a macro with arguments. It uses the files
define_args.orc and define_args.sco.

Example 2. Example of the define macro with arguments.

 /* define_args.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Define the oscillator macro.
 #define OSCMACRO(VOLUME'FREQ'TABLE) #oscil $VOLUME, $FREQ, $TABLE#

 ; Instrument #1
 instr 1
; Use the oscillator macro.
; This will be expanded to "a1 oscil 5000, 440, 1".
a1 $OSCMACRO(5000'440'1)

; Send it to the output.
out a1
 endin
 /* define_args.orc */

 /* define_args.sco */
 /* Written by Kevin Conder */
 ; Define Table #1 with an ordinary sine wave.
 f 1 0 32768 10 1
 ; Play Instrument #1 for two seconds.
 i 1 0 2
 e
 /* define_args.sco */

Its output should include lines like this:

 Macro definition for OSCMACRO

See Also		~

|dollar| $NAME, |undef| #undef

Credits		~

Author: John ffitch              
University of Bath/Codemist Ltd. 
Bath, UK                         
April 1998                       

New in Csound version 3.48

------------------------------------------------------------------------------
*include*
#include	~

#include --  Includes an external file for processing.

Description		~

Includes an external file for processing.

Syntax		~

#include "filename"

Performance		~

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

 #include "filename"

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

This takes input from the named file until it ends, when input reverts to the
previous input. There is currently a limit of 20 on the depth of included
files and macros.

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

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

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

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

Examples		~

Here is an example of the include opcode. It uses the files include.orc,
include.sco, and table1.inc.

Example 1. Example of the include opcode.

 /* include.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1 - a basic oscillator.
 instr 1
kamp = 10000
kcps = 440
ifn = 1

a1 oscil kamp, kcps, ifn
out a1
 endin
 /* include.orc */

 /* table1.inc */
 /* Written by Kevin Conder */
 ; Table #1, a sine wave.
 f 1 0 16384 10 1
 /* table1.inc */

 /* include.sco */
 /* Written by Kevin Conder */

 ; Include the file for Table #1.
 #include "table1.inc"

 ; Play Instrument #1 for 2 seconds.
 i 1 0 2
 e
 /* include.sco */

Credits		~

Author: John ffitch              
University of Bath/Codemist Ltd. 
Bath, UK                         
April 1998                       

New in Csound version 3.48

------------------------------------------------------------------------------
*undef*
#undef	~

#undef --  Un-defines a macro.

Description		~

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

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

Syntax		~

#undef NAME

Initialization		~

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

Performance		~

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

See Also		~

|define| #define, |dollar| $NAME

Credits		~

Author: John ffitch              
University of Bath/Codemist Ltd. 
Bath, UK                         
April 1998                       

New in Csound version 3.48

------------------------------------------------------------------------------
*dollar*
$NAME	~

$NAME --  Calls a defined macro.

Description		~

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

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

Syntax		~

$NAME

Initialization		~

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

Performance		~

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

Examples		~

Here is an example of the calling a macro. It uses the files define.orc and
define.sco.

Example 1. An example of the calling a macro.

 /* define.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Define the macros.
 #define VOLUME #5000#
 #define FREQ #440#
 #define TABLE #1#

 ; Instrument #1
 instr 1
; Use the macros.
; This will be expanded to "a1 oscil 5000, 440, 1".
a1 oscil $VOLUME, $FREQ, $TABLE

; Send it to the output.
out a1
 endin
 /* define.orc */

 /* define.sco */
 /* Written by Kevin Conder */
 ; Define Table #1 with an ordinary sine wave.
 f 1 0 32768 10 1
 ; Play Instrument #1 for two seconds.
 i 1 0 2
 e
 /* define.sco */

Its output should include lines like this:

 Macro definition for VOLUME
 Macro definition for CPS
 Macro definition for TABLE

Here is an example of the calling a macro with arguments. It uses the files
define_args.orc and define_args.sco.

Example 2. An example of the calling a macro with arguments.

 /* define_args.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Define the oscillator macro.
 #define OSCMACRO(VOLUME'FREQ'TABLE) #oscil $VOLUME, $FREQ, $TABLE#

 ; Instrument #1
 instr 1
; Use the oscillator macro.
; This will be expanded to "a1 oscil 5000, 440, 1".
a1 $OSCMACRO(5000'440'1)

; Send it to the output.
out a1
 endin
 /* define_args.orc */

 /* define_args.sco */
 /* Written by Kevin Conder */
 ; Define Table #1 with an ordinary sine wave.
 f 1 0 32768 10 1
 ; Play Instrument #1 for two seconds.
 i 1 0 2
 e
 /* define_args.sco */

Its output should include a line like this:

 Macro definition for OSCMACRO

See Also		~

|define| #define, |undef| #undef

Credits		~

Author: John ffitch              
University of Bath/Codemist Ltd. 
Bath, UK                         
April, 1998                      

New in Csound version 3.48

------------------------------------------------------------------------------
*modulus*
%	~

% --  Modulus operator.

Description		~

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

a + b * c.

In such cases three rules apply:

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

a + (b * c)

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

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

a && b - c || d

is taken as

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

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

a - b - c i

is taken as

(a - b) - c

Parentheses may be used as above to force particular groupings.

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

Syntax		~

a % b (no rate restriction)

where the arguments a and b may be further expressions.

Examples		~

Here is an example of the % operator. It uses the files modulus.orc and
modulus.sco.

Example 1. Example of the % operator.

 /* modulus.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
i1 = 5 % 3
print i1
 endin
 /* modulus.orc */

 /* modulus.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* modulus.sco */

Its output should include a line like this:

 instr 1:  i1 = 2.000

See Also		~

|subtracts| -, |adds| +, |opand| &&, |opor| ||, |multiplies| *, |divides| /,
|raises| ^

------------------------------------------------------------------------------
*opand*
&&	~

&& --  Logical AND operator.

Description		~

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

a + b * c.

In such cases three rules apply:

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

a + (b * c)

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

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

a && b - c || d

is taken as

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

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

a - b - c i

is taken as

(a - b) - c

Parentheses may be used as above to force particular groupings.

Syntax		~

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

where the arguments a and b may be further expressions.

See Also		~

|subtracts| -, |adds| +, |opor| ||, |multiplies| *, |divides| /, |raises| ^,
|modulus| %

------------------------------------------------------------------------------
*greaterthan*
>	~

> --  Determines if one value is greater than another.

Description		~

Determines if one value is greater than another.

Syntax		~

(a > b ? v1 : v2)

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

Performance		~

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

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

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

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

Examples		~

Here is an example of the > opcode. It uses the files greaterthan.orc and
greaterthan.sco.

Example 1. Example of the > opcode.

 /* greaterthan.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 44100
 ksmps = 1
 nchnls = 1

 ; Instrument #1.
 instr 1
; Get the 4th p-field from the score.
k1 =  p4

; Is it greater than 3? (1 = true, 0 = false)
k2 = (p4 > 3 ? 1 : 0)

; Print the values of k1 and k2.
printks "k1 = %f, k2 = %f\\n", 1, k1, k2
 endin
 /* greaterthan.orc */

 /* greaterthan.sco */
 /* Written by Kevin Conder */
 ; Call Instrument #1 with a p4 = 2.
 i 1 0 0.5 2
 ; Call Instrument #1 with a p4 = 3.
 i 1 1 0.5 3
 ; Call Instrument #1 with a p4 = 4.
 i 1 2 0.5 4
 e
 /* greaterthan.sco */

Its output should include lines like this:

 k1 = 2.000000, k2 = 0.000000
 k1 = 3.000000, k2 = 0.000000
 k1 = 4.000000, k2 = 1.000000

See Also		~

|equals| ==, |greaterequal| >=, |lessequal| <=, |lessthan| <, |notequal| !=

------------------------------------------------------------------------------
*greaterequal*
>=	~

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

Description		~

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

Syntax		~

(a >= b ? v1 : v2)

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

Performance		~

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

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

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

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

Examples		~

Here is an example of the >= opcode. It uses the files greaterequal.orc and
greaterequal.sco.

Example 1. Example of the >= opcode.

 /* greaterequal.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 44100
 ksmps = 1
 nchnls = 1

 ; Instrument #1.
 instr 1
; Get the 4th p-field from the score.
k1 =  p4

; Is it greater than or equal to 3? (1 = true, 0 = false)
k2 = (p4 >= 3 ? 1 : 0)

; Print the values of k1 and k2.
printks "k1 = %f, k2 = %f\\n", 1, k1, k2
 endin
 /* greaterequal.orc */

 /* greaterequal.sco */
 /* Written by Kevin Conder */
 ; Call Instrument #1 with a p4 = 2.
 i 1 0 0.5 2
 ; Call Instrument #1 with a p4 = 3.
 i 1 1 0.5 3
 ; Call Instrument #1 with a p4 = 4.
 i 1 2 0.5 4
 e
 /* greaterequal.sco */

Its output should include lines like this:

 k1 = 2.000000, k2 = 0.000000
 k1 = 3.000000, k2 = 1.000000
 k1 = 4.000000, k2 = 1.000000

See Also		~

|equals| ==, |greaterthan| >, |lessequal| <=, |lessthan| <, |notequal| !=

------------------------------------------------------------------------------
*lessthan*
<	~

< --  Determines if one value is less than another.

Description		~

Determines if one value is less than another.

Syntax		~

(a < b ? v1 : v2)

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

Performance		~

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

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

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

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

Examples		~

Here is an example of the < opcode. It uses the files lessthan.orc and
lessthan.sco.

Example 1. Example of the < opcode.

 /* lessthan.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 44100
 ksmps = 1
 nchnls = 1

 ; Instrument #1.
 instr 1
; Get the 4th p-field from the score.
k1 =  p4

; Is it less than 3? (1 = true, 0 = false)
k2 = (p4 < 3 ? 1 : 0)

; Print the values of k1 and k2.
printks "k1 = %f, k2 = %f\\n", 1, k1, k2
 endin
 /* lessthan.orc */

 /* lessthan.sco */
 /* Written by Kevin Conder */
 ; Call Instrument #1 with a p4 = 2.
 i 1 0 0.5 2
 ; Call Instrument #1 with a p4 = 3.
 i 1 1 0.5 3
 ; Call Instrument #1 with a p4 = 4.
 i 1 2 0.5 4
 e
 /* lessthan.sco */

Its output should include lines like this:

 k1 = 2.000000, k2 = 1.000000
 k1 = 3.000000, k2 = 0.000000
 k1 = 4.000000, k2 = 0.000000

See Also		~

|equals| ==, |greaterequal| >=, |greaterthan| >, |lessequal| <=, |notequal|
!=

------------------------------------------------------------------------------
*lessequal*
<=	~

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

Description		~

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

Syntax		~

(a <= b ? v1 : v2)

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

Performance		~

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

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

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

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

Examples		~

Here is an example of the <= opcode. It uses the files lessequal.orc and
lessequal.sco.

Example 1. Example of the <= opcode.

 /* lessequal.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 44100
 ksmps = 1
 nchnls = 1

 ; Instrument #1.
 instr 1
; Get the 4th p-field from the score.
k1 =  p4

; Is it less than or equal to 3? (1 = true, 0 = false)
k2 = (p4 <= 3 ? 1 : 0)

; Print the values of k1 and k2.
printks "k1 = %f, k2 = %f\\n", 1, k1, k2
 endin
 /* lessequal.orc */

 /* lessequal.sco */
 /* Written by Kevin Conder */
 ; Call Instrument #1 with a p4 = 2.
 i 1 0 0.5 2
 ; Call Instrument #1 with a p4 = 3.
 i 1 1 0.5 3
 ; Call Instrument #1 with a p4 = 4.
 i 1 2 0.5 4
 e
 /* lessequal.sco */

Its output should include lines like this:

 k1 = 2.000000, k2 = 1.000000
 k1 = 3.000000, k2 = 1.000000
 k1 = 4.000000, k2 = 0.000000

See Also		~

|equals| ==, |greaterequal| >=, |greaterthan| >, |lessthan| <, |notequal| !=

------------------------------------------------------------------------------
*multiplies*
*	~

* --  Multiplication operator.

Description		~

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

a + b * c.

In such cases three rules apply:

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

a + (b * c)

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

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

a && b - c || d

is taken as

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

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

a - b - c i

is taken as

(a - b) - c

Parentheses may be used as above to force particular groupings.

Syntax		~

a * b (no rate restriction)

where the arguments a and b may be further expressions.

Examples		~

Here is an example of the * operator. It uses the files multiplies.orc and
multiplies.sco.

Example 1. Example of the * operator.

 /* multiplies.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
i1 = 24 * 8
print i1
 endin
 /* multiplies.orc */

 /* multiplies.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* multiplies.sco */

Its output should include a line like this:

 instr 1:  i1 = 192.000

See Also		~

|subtracts| -, |adds| +, |opand| &&, |opor| ||, |divides| /, |raises| ^,
|modulus| %

------------------------------------------------------------------------------
*adds*
+	~

+ --  Addition operator

Description		~

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

a + b * c.

In such cases three rules apply:

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

a + (b * c)

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

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

a && b - c || d

is taken as

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

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

a - b - c i

is taken as

(a - b) - c

Parentheses may be used as above to force particular groupings.

Syntax		~

+ a (no rate restriction)

where the arguments a and b may be further expressions.

Examples		~

Here is an example of the + operator. It uses the files adds.orc and
adds.sco.

Example 1. Example of the + operator.

 /* adds.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
i1 = 24 + 8
print i1
 endin
 /* adds.orc */

 /* adds.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* adds.sco */

Its output should include lines like:

 instr 1:  i1 = 32.000

See Also		~

|subtracts| -, |opand| &&, |opor| ||, |multiplies| *, |divides| /, |raises|
^, |modulus| %

------------------------------------------------------------------------------
*subtracts*
-	~

- --  Subtraction operator.

Description		~

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

a + b * c.

In such cases three rules apply:

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

a + (b * c)

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

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

a && b - c || d

is taken as

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

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

a - b - c i

is taken as

(a - b) - c

Parentheses may be used as above to force particular groupings.

Syntax		~

- a (no rate restriction)

where the arguments a and b may be further expressions.

Examples		~

Here is an example of the - operator. It uses the files subtracts.orc and
subtracts.sco.

Example 1. Example of the - operator.

 /* subtracts.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
i1 = 24 - 8
print i1
 endin
 /* subtracts.orc */

 /* subtracts.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* subtracts.sco */

Its output should include lines like this:

 instr 1:  i1 = 16.000

See Also		~

|adds| +, |opand| &&, |opor| ||, |multiplies| *, |divides| /, |raises| ^,
|modulus| %

------------------------------------------------------------------------------
*divides*
/	~

/ --  Division operator.

Description		~

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

a + b * c.

In such cases three rules apply:

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

a + (b * c)

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

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

a && b - c || d

is taken as

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

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

a - b - c i

is taken as

(a - b) - c

Parentheses may be used as above to force particular groupings.

Syntax		~

a / b (no rate restriction)

where the arguments a and b may be further expressions.

Examples		~

Here is an example of the / operator. It uses the files divides.orc and
divides.sco.

Example 1. Example of the / operator.

 /* divides.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
i1 = 24 / 8
print i1
 endin
 /* divides.orc */

 /* divides.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* divides.sco */

Its output should include lines like this:

 instr 1:  i1 = 3.000

See Also		~

|subtracts| -, |adds| +, |opand| &&, |opor| ||, |multiplies| *, |raises| ^,
|modulus| %

------------------------------------------------------------------------------
*assign*
=	~

= --  Performs a simple assignment.

Syntax		~

ar = xarg

ir = iarg

kr = karg

Description		~

Performs a simple assignment.

Initialization		~

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

Examples		~

Here is an example of the assign opcode. It uses the files assign.orc and
assign.sco.

Example 1. Example of the assign opcode.

 /* assign.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Assign a value to the variable i1.
i1 = 1234

; Print the value of the i1 variable.
print i1
 endin
 /* assign.orc */

 /* assign.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* assign.sco */

Its output should include a line like this:

 instr 1:  i1 = 1234.000

See Also		~

|divz| divz, |init| init, |tival| tival

------------------------------------------------------------------------------
*equals*
==	~

== --  Compares two values for equality.

Description		~

Compares two values for equality.

Syntax		~

(a == b ? v1 : v2)

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

Performance		~

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

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

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

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

Examples		~

Here is an example of the == opcode. It uses the files equal.orc and
equal.sco.

Example 1. Example of the == opcode.

 /* equal.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 44100
 ksmps = 1
 nchnls = 1

 ; Instrument #1.
 instr 1
; Get the 4th p-field from the score.
k1 =  p4

; Is it equal to 3? (1 = true, 0 = false)
k2 = (p4 == 3 ? 1 : 0)

; Print the values of k1 and k2.
printks "k1 = %f, k2 = %f\\n", 1, k1, k2
 endin
 /* equal.orc */

 /* equal.sco */
 /* Written by Kevin Conder */
 ; Call Instrument #1 with a p4 = 2.
 i 1 0 0.5 2
 ; Call Instrument #1 with a p4 = 3.
 i 1 1 0.5 3
 ; Call Instrument #1 with a p4 = 4.
 i 1 2 0.5 4
 e
 /* equal.sco */

Its output should include lines like this:

 k1 = 2.000000, k2 = 0.000000
 k1 = 3.000000, k2 = 1.000000
 k1 = 4.000000, k2 = 0.000000

See Also		~

|greaterequal| >=, |greaterthan| >, |lessequal| <=, |lessthan| <, |notequal|
!=

------------------------------------------------------------------------------
*raises*
^	~

^ --  "Power of" operator.

Description		~

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

a + b * c.

In such cases three rules apply:

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

a + (b * c)

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

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

a && b - c || d

is taken as

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

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

a - b - c i

is taken as

(a - b) - c

Parentheses may be used as above to force particular groupings.

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

Syntax		~

a ^ b (b not audio-rate)

where the arguments a and b may be further expressions.

Examples		~

Here is an example of the ^ operator. It uses the files raises.orc and
raises.sco.

Example 1. Example of the ^ operator.

 /* raises.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
i1 = 2 ^ 12
print i1
 endin
 /* raises.orc */

 /* raises.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* raises.sco */

Its output should include a line like this:

 instr 1:  i1 = 4096.000

See Also		~

|subtracts| -, |adds| +, |opand| &&, |opor| ||, |multiplies| *, |divides| /,
|modulus| %

------------------------------------------------------------------------------
*opor*
||	~

|| --  Logical OR operator.

Description		~

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

a + b * c.

In such cases three rules apply:

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

a + (b * c)

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

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

a && b - c || d

is taken as

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

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

a - b - c i

is taken as

(a - b) - c

Parentheses may be used as above to force particular groupings.

Syntax		~

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

where the arguments a and b may be further expressions.

See Also		~

|subtracts| -, |adds| +, |opand| &&, |multiplies| *, |divides| /, |raises| ^,
|modulus| %

------------------------------------------------------------------------------
*zerodbfs*
0dbfs	~

0dbfs --  Sets the value of 0 decibels using full scale amplitude.

Description		~

Sets the value of 0 decibels using full scale amplitude.

Syntax		~

0dbfs = iarg

Initialization		~

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

Performance		~

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

These calls should all work:

 ipeak = 0dbfs

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

and so on.

As for documentation: the usage should be obvious - the main thing is for
people to start to code 0dbfs-relatively (and use the |ampdb| ampdb() opcodes
a lot more!), rather than use explicit sample values.

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

  BIG NB                                                                      
  All the main sample formats are supported, but I haven't got around to      
  dealing with the char formats. Probably it's straight-forward...            
  I have tried to cover the main utils - adsyn,lpanal etc. But there are      
  bound to be things missing, sorry.                                          
  Some of the parsing code is a bit grungy because I have a variable with a   
  leading digit!                                                              

Examples		~

Here is an example of the 0dbfs opcode. It uses the files 0dbfs.orc and
0dbfs.sco.

Example 1. Example of the 0dbfs opcode.

 /* 0dbfs.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Set the 0dbfs to the 16-bit maximum.
 0dbfs = 32767

 ; Instrument #1.
 instr 1
; Linearly increase the amplitude value "kamp" from
; 0 to 1 over the duration defined by p3.
kamp line 0, p3, 1

; Generate a basic tone using our amplitude value.
a1 oscil kamp, 440, 1

; Multiply the basic tone (with its amplitude between
; 0 and 1) by the full-scale 0dbfs value.
out a1 * 0dbfs
 endin
 /* 0dbfs.orc */

 /* 0dbfs.sco */
 /* Written by Kevin Conder */
 ; Table #1, a sine wave.
 f 1 0 16384 10 1

 ; Play Instrument #1 for three seconds.
 i 1 0 3
 e
 /* 0dbfs.sco */

Credits		~

Author: Richard Dobson 
May 2002               

New in version 4.20

------------------------------------------------------------------------------
*opa*
a	~

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

Description		~

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

Syntax		~

a(x) (control-rate args only)

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

Examples		~

Here is an example of the a opcode. It uses the files a.orc and a.sco.

Example 1. Example of the a opcode.

 /* a.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Create a sine wave at k-rate.
kwave oscil 20000, 440, 1

; Convert the k-rate sine wave to the audio-rate.
awave = a(kwave)

; Output the audio-rate version of sine wave.
out awave
 endin
 /* a.orc */

 /* a.sco */
 /* Written by Kevin Conder */
 ; Table #1, a sine wave.
 f 1 0 16384 10 1

 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* a.sco */

See Also		~

|opi| i

Credits		~

Author: Gabriel Maldonado

New in version 4.21

------------------------------------------------------------------------------
*abetarand*
abetarand	~

abetarand --  Deprecated.

Description		~

Deprecated as of version 3.49. Use the |betarand| betarand opcode instead.

------------------------------------------------------------------------------
*abexprnd*
abexprnd	~

abexprnd --  Deprecated.

Description		~

Deprecated as of version 3.49. Use the |bexprnd| bexprnd opcode instead.

------------------------------------------------------------------------------
*abs*
abs	~

abs --  Returns an absolute value.

Description		~

Returns the absolute value of x.

Syntax		~

abs(x) (no rate restriction)

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

Examples		~

Here is an example of the abs opcode. It uses the files abs.orc and abs.sco.

Example 1. Example of the abs opcode.

 /* abs.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
i1 = -6
i2 = abs(i1)

print i2
 endin
 /* abs.orc */

 /* abs.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* abs.sco */

Its output should include lines like:

 instr 1:  i2 = 6.000

See Also		~

|exp| exp, |frac| frac, |int| int, |log| log, |log10| log10, |opi| i, |sqrt|
sqrt

------------------------------------------------------------------------------
*acauchy*
acauchy	~

acauchy --  Deprecated.

Description		~

Deprecated as of version 3.49. Use the |cauchy| cauchy opcode instead.

------------------------------------------------------------------------------
*active*
active	~

active --  Returns the number of active instances of an instrument.

Description		~

Returns the number of active instances of an instrument.

Syntax		~

ir active insnum

kr active kinsnum

Initialization		~

insnum -- number of the instrument to be reported

Performance		~

kinsnum -- number of the instrument to be reported

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

Examples		~

Here is a simple example of the active opcode. It uses the files active.orc
and active.sco.

Example 1. Simple example of the active opcode.

 /* active.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1 - a noisy waveform.
 instr 1
; Generate a really noisy waveform.
anoisy rand 44100
; Turn down its amplitude.
aoutput gain anoisy, 2500
; Send it to the output.
out aoutput
 endin

 ; Instrument #2 - counts active instruments.
 instr 2
; Count the active instances of Instrument #1.
icount active 1
; Print the number of active instances.
print icount
 endin
 /* active.orc */

 /* active.sco */
 /* Written by Kevin Conder */
 ; Start the first instance of Instrument #1 at 0:00 seconds.
 i 1 0.0 3.0

 ; Start the second instance of Instrument #1 at 0:015 seconds.
 i 1 1.5 1.5

 ; Play Instrument #2 at 0:01 seconds, when we have only
 ; one active instance of Instrument #1.
 i 2 1.0 0.1

 ; Play Instrument #2 at 0:02 seconds, when we have
 ; two active instances of Instrument #1.
 i 2 2.0 0.1
 e
 /* active.sco */

Its output should include lines like this:

 instr 2:  icount = 1.000
 instr 2:  icount = 2.000

Here is a more advanced example of the active opcode. It displays the results
of the active opcode at k-rate instead of i-rate. It uses the files
active_k.orc and active_k.sco.

Example 2. Example of the active opcode at k-rate.

 /* active_k.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1 - a noisy waveform.
 instr 1
; Generate a really noisy waveform.
anoisy rand 44100
; Turn down its amplitude.
aoutput gain anoisy, 2500
; Send it to the output.
out aoutput
 endin

 ; Instrument #2 - counts active instruments at k-rate.
 instr 2
; Count the active instances of Instrument #1.
kcount active 1
; Print the number of active instances.
printk2 kcount
 endin
 /* active_k.orc */

 /* active_k.sco */
 /* Written by Kevin Conder */
 ; Start the first instance of Instrument #1 at 0:00 seconds.
 i 1 0.0 3.0

 ; Start the second instance of Instrument #1 at 0:015 seconds.
 i 1 1.5 1.5

 ; Play Instrument #2 at 0:01 seconds, when we have only
 ; one active instance of Instrument #1.
 i 2 1.0 0.1

 ; Play Instrument #2 at 0:02 seconds, when we have
 ; two active instances of Instrument #1.
 i 2 2.0 0.1
 e
 /* active_k.sco */

Its output should include lines like:

i2     1.00000
i2     2.00000

Credits		~

Author: John ffitch              
University of Bath/Codemist Ltd. 
Bath, UK                         
July, 1999                       

New in Csound version 3.57

------------------------------------------------------------------------------
*adsr*
adsr	~

adsr --  Calculates the classical ADSR envelope using linear segments.

Description		~

Calculates the classical ADSR envelope using linear segments.

Syntax		~

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

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

Initialization		~

iatt -- duration of attack phase

idec -- duration of decay

islev -- level for sustain phase

irel -- duration of release phase

idel -- period of zero before the envelope starts

Performance		~

The envelope is the range 0 to 1 and may need to be scaled further. The
envelope may be described as:

Picture of an ADSR envelope.

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

adsr is new in Csound version 3.49.

Examples		~

Here is an example of the adsr opcode. It uses the files adsr.orc and
adsr.sco.

Example 1. Example of the adsr opcode.

 /* adsr.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1 - a simple instrument.
 instr 1
; Set the amplitude.
kamp init 20000
; Get the frequency from the fourth p-field.
kcps = cpspch(p4)

a1 vco kamp, kcps, 1
out a1
 endin

 ; Instrument #2 - instrument with an ADSR envelope.
 instr 2
iatt = 0.05
idec =  0.5
islev = 0.08
irel = 0.008

; Create an amplitude envelope.
kenv adsr iatt, idec, islev, irel
kamp = kenv * 20000

; Get the frequency from the fourth p-field.
kcps = cpspch(p4)

a1 vco kamp, kcps, 1
out a1
 endin
 /* adsr.orc */

 /* adsr.sco */
 /* Written by Kevin Conder */
 ; Table #1, a sine wave.
 f 1 0 16384 10 1

 ; Set the tempo to 120 beats per minute.
 t 0 120

 ; Play a melody with Instrument #1.
 ; p4 = frequency in pitch-class notation.
 i  1  0   1  8.04
 i  1  1   1  8.04
 i  1  2   1  8.05
 i  1  3   1  8.07
 i  1  4   1  8.07
 i  1  5   1  8.05
 i  1  6   1  8.04
 i  1  7   1  8.02
 i  1  8   1  8.00
 i  1  9   1  8.00
 i  1  10  1  8.02
 i  1  11  1  8.04
 i  1  12  2  8.04
 i  1  14  2  8.02

 ; Repeat the melody with Instrument #2.
 ; p4 = frequency in pitch-class notation.
 i  2  16  1  8.04
 i  2  17  1  8.04
 i  2  18  1  8.05
 i  2  19  1  8.07
 i  2  20  1  8.07
 i  2  21  1  8.05
 i  2  22  1  8.04
 i  2  23  1  8.02
 i  2  24  1  8.00
 i  2  25  1  8.00
 i  2  26  1  8.02
 i  2  27  1  8.04
 i  2  28  2  8.04
 i  2  30  2  8.02
 e
 /* adsr.sco */

See Also		~

|madsr| madsr, |mxadsr| mxadsr, |xadsr| xadsr

------------------------------------------------------------------------------
*adsyn*
adsyn	~

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

Description		~

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

Syntax		~

ar adsyn kamod, kfmod, ksmod, ifilcod

Initialization		~

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

Performance		~

kamod -- amplitude factor of the contributing partials.

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

ksmod -- speed factor of the contributing partials.

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

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

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

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

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

Examples		~

Here is an example of the adsyn opcode. It uses the files adsyn.orc,
adsyn.sco, and kickroll.het. The file "kickroll.het" was created by using the
|hetro| hetro utility with the audio file kickroll.wav.

Example 1. Example of the adsyn opcode.

 /* adsyn.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; If the modulation amounts are set to 1, adsyn
; will not perform any special modulation.
kamod init 1
kfmod init 1
ksmod init 1

; Re-synthesizes the file "kickroll.het".
a1 adsyn kamod, kfmod, ksmod, "kickroll.het"

out a1 * 32768
 endin
 /* adsyn.orc */

 /* adsyn.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* adsyn.sco */

------------------------------------------------------------------------------
*adsynt*
adsynt	~

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

Description		~

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

Syntax		~

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

Initialization		~

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

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

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

icnt -- number of partials to be generated

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

Performance		~

kamp -- amplitude of note

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

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

Examples		~

Here is an example of the adsynt opcode. It uses the files adsynt.orc and
adsynt.sco. These two instruments perform additive synthesis. The output of
each sounds like a Tibetan bowl. The first one is static, as parameters are
only generated at init-time. In the second one, parameters are continuously
changed.

Example 1. Example of the adsynt opcode.

 /* adsynt.orc */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Generate a sinewave table.
 giwave ftgen 1, 0, 1024, 10, 1
 ; Generate two empty tables for adsynt.
 gifrqs ftgen 2, 0, 32, 7, 0, 32, 0
 ; A table for freqency and amp parameters.
 giamps ftgen 3, 0, 32, 7, 0, 32, 0

 ; Generates parameters at init time
 instr 1
; Generate 10 voices.
icnt = 10
; Init loop index.
index = 0

 ; Loop only executed at init time.
 loop:
; Define non-harmonic partials.
ifreq pow index + 1, 1.5
; Define amplitudes.
iamp = 1 / (index+1)
; Write to tables.
tableiw ifreq, index, gifrqs
; Used by adsynt.
tableiw iamp, index, giamps

index = index + 1
; Do loop/
if (index < icnt) igoto loop

asig adsynt 5000, 150, giwave, gifrqs, giamps, icnt
out asig
 endin

 ; Generates parameters every k-cycle.
 instr 2
; Generate 10 voices.
icnt = 10
; Reset loop index.
kindex = 0

 ; Loop executed every k-cycle.
 loop:
; Generate lfo for frequencies.
kspeed  pow kindex + 1, 1.6
; Individual phase for each voice.
kphas phasorbnk kspeed * 0.7, kindex, icnt
klfo table kphas, giwave, 1
; Arbitrary parameter twiddling...
kdepth pow 1.4, kindex
kfreq pow kindex + 1, 1.5
kfreq = kfreq + klfo*0.006*kdepth

; Write freqs to table for adsynt.
tablew kfreq, kindex, gifrqs

; Generate lfo for amplitudes.
kspeed  pow kindex + 1, 0.8
; Individual phase for each voice.
kphas phasorbnk kspeed*0.13, kindex, icnt, 2
klfo table kphas, giwave, 1
; Arbitrary parameter twiddling...
kamp pow 1 / (kindex + 1), 0.4
kamp = kamp * (0.3+0.35*(klfo+1))

; Write amps to table for adsynt.
tablew kamp, kindex, giamps

kindex = kindex + 1
; Do loop.
if (kindex < icnt) kgoto loop

asig adsynt 5000, 150, giwave, gifrqs, giamps, icnt
out asig
 endin
 /* adsynt.orc */

 /* adsynt.sco */
 ; Play Instrument #1 for 2.5 seconds.
 i 1 0 2.5
 ; Play Instrument #2 for 2.5 seconds.
 i 2 3 2.5
 e
 /* adsynt.sco */

Credits		~

Author: Peter Neubäcker 
Munich, Germany         
August, 1999            

New in Csound version 3.58

------------------------------------------------------------------------------
*aexprand*
aexprand	~

aexprand --  Deprecated.

Description		~

Deprecated as of version 3.49. Use the |exprand| exprand opcode instead.

------------------------------------------------------------------------------
*aftouch*
aftouch	~

aftouch --  Get the current after-touch value for this channel.

Description		~

Get the current after-touch value for this channel.

Syntax		~

kaft aftouch [imin] [, imax]

Initialization		~

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

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

Performance		~

Get the current after-touch value for this channel. Note that this access to
pitch-bend data is independent of the MIDI pitch, enabling the value here to
be used for any arbitrary purpose.

Examples		~

Here is an example of the aftouch opcode. It uses the files aftouch.orc and
aftouch.sco.

Example 1. Example of the aftouch opcode.

 /* aftouch.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
k1 aftouch

printk2 k1
 endin
 /* aftouch.orc */

 /* aftouch.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for 12 seconds.
 i 1 0 12
 e
 /* aftouch.sco */

See Also		~

|ampmidi| ampmidi, |cpsmidi| cpsmidi, |cpsmidib| cpsmidib, |midictrl|
midictrl, |notnum| notnum, |octmidi| octmidi, |octmidib| octmidib, |pchbend|
pchbend, |pchmidi| pchmidi, |pchmidib| pchmidib, |veloc| veloc

Credits		~

Author: Barry L. Vercoe - Mike Berry 
MIT - Mills                          
May 1997                             

------------------------------------------------------------------------------
*agauss*
agauss	~

agauss --  Deprecated.

Description		~

Deprecated as of version 3.49. Use the |gauss| gauss opcode instead.

------------------------------------------------------------------------------
*agogobel*
agogobel	~

agogobel --  Deprecated.

Description		~

Deprecated as of version 3.52. Use the |gogobel| gogobel opcode instead.

------------------------------------------------------------------------------
*alinrand*
alinrand	~

alinrand --  Deprecated.

Description		~

Deprecated as of version 3.49. Use the |linrand| linrand opcode instead.

------------------------------------------------------------------------------
*alpass*
alpass	~

alpass --  Reverberates an input signal with a flat frequency response.

Description		~

Reverberates an input signal with a flat frequency response.

Syntax		~

ar alpass asig, krvt, ilpt [, iskip] [, insmps]

Initialization		~

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

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

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

Performance		~

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

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

Examples		~

Here is an example of the alpass opcode. It uses the files alpass.orc and
alpass.sco.

Example 1. Example of the alpass opcode.

 /* alpass.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Initialize the audio mixer.
 gamix init 0

 ; Instrument #1.
 instr 1
; Generate a source signal.
a1 oscili 30000, cpspch(p4), 1
; Output the direct sound.
out a1 

; Add the source signal to the audio mixer.
gamix = gamix + a1
 endin

 ; Instrument #99 (highest instr number executed last)
 instr 99
krvt = 1.5
ilpt = 0.1

; Filter the mixed signal.
a99 alpass gamix, krvt, ilpt
; Output the result.
out a99

; Empty the mixer for the next pass.
gamix = 0
 endin
 /* alpass.orc */

 /* alpass.sco */
 ; Table #1, a sine wave.
 f 1 0 128 10 1

 ; p4 = frequency (in a pitch-class)
 ; Play Instrument #1 for a tenth of a second, p4=7.00
 i 1 0 0.1 7.00
 ; Play Instrument #1 for a tenth of a second, p4=7.02
 i 1 1 0.1 7.02
 ; Play Instrument #1 for a tenth of a second, p4=7.04
 i 1 2 0.1 7.04
 ; Play Instrument #1 for a tenth of a second, p4=7.06
 i 1 3 0.1 7.06

 ; Make sure the filter remains active.
 i 99 0 5
 e
 /* alpass.sco */

See Also		~

|comb| comb, |reverb| reverb, |valpass| valpass, |vcomb| vcomb

Credits		~

Author: William "Pete" Moss (vcomb and valpass) 
University of Texas at Austin                   
Austin, Texas USA                               
January 2002                                    

------------------------------------------------------------------------------
*ampdb*
ampdb	~

ampdb --  Returns the amplitude equivalent of the decibel value x.

Description		~

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

  * 60 dB = 1000

  * 66 dB = 1995.262

  * 72 dB = 3891.07

  * 78 dB = 7943.279

  * 84 dB = 15848.926

  * 90 dB = 31622.764

Syntax		~

ampdb(x) (no rate restriction)

Examples		~

Here is an example of the ampdb opcode. It uses the files ampdb.orc and
ampdb.sco.

Example 1. Example of the ampdb opcode.

 /* ampdb.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
idb = 90
iamp = ampdb(idb)

print iamp
 endin
 /* ampdb.orc */

 /* ampdb.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* ampdb.sco */

Its output should include lines like:

 instr 1:  iamp = 31622.764

See Also		~

|ampdbfs| ampdbfs, |db| db, |dbamp| dbamp, |dbfsamp| dbfsamp

------------------------------------------------------------------------------
*ampdbfs*
ampdbfs	~

ampdbfs --  Returns the amplitude equivalent of the decibel value x, which is
relative to full scale amplitude.

Description		~

Returns the amplitude equivalent of the decibel value x, which is relative to
full scale amplitude. Full scale is assumed to be 16 bit. New is Csound
version 4.10.

Syntax		~

ampdbfs(x) (no rate restriction)

Examples		~

Here is an example of the ampdbfs opcode. It uses the files ampdbfs.orc and
ampdbfs.sco.

Example 1. Example of the ampdbfs opcode.

 /* ampdbfs.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
idb = -1
iamp = ampdbfs(idb)

print iamp
 endin
 /* ampdbfs.orc */

 /* ampdbfs.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* ampdbfs.sco */

Its output should include lines like:

 instr 1:  iamp = 29203.621

See Also		~

|ampdb| ampdb, |dbamp| dbamp, |dbfsamp| dbfsamp

------------------------------------------------------------------------------
*ampmidi*
ampmidi	~

ampmidi --  Get the velocity of the current MIDI event.

Description		~

Get the velocity of the current MIDI event.

Syntax		~

iamp ampmidi iscal [, ifn]

Initialization		~

iscal -- i-time scaling factor

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

Performance		~

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

Examples		~

Here is an example of the ampmidi opcode. It uses the files ampmidi.orc and
ampmidi.sco.

Example 1. Example of the ampmidi opcode.

 /* ampmidi.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Scale the amplitude between 0 and 1.
i1 ampmidi 1

print i1
 endin
 /* ampmidi.orc */

 /* ampmidi.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for 12 seconds.
 i 1 0 12
 e
 /* ampmidi.sco */

See Also		~

|aftouch| aftouch, |cpsmidi| cpsmidi, |cpsmidib| cpsmidib, |midictrl|
midictrl, |notnum| notnum, |octmidi| octmidi, |octmidib| octmidib, |pchbend|
pchbend, |pchmidi| pchmidi, |pchmidib| pchmidib, |veloc| veloc

Credits		~

Author: Barry L. Vercoe - Mike Berry 
MIT - Mills                          
May 1997                             

------------------------------------------------------------------------------
*apcauchy*
apcauchy	~

apcauchy --  Deprecated.

Description		~

Deprecated as of version 3.49. Use the |pcauchy| pcauchy opcode instead.

------------------------------------------------------------------------------
*apoisson*
apoisson	~

apoisson --  Deprecated.

Description		~

Deprecated as of version 3.49. Use the |poisson| poisson opcode instead.

------------------------------------------------------------------------------
*apow*
apow	~

apow --  Deprecated.

Description		~

Deprecated as of version 3.48. Use the |pow| pow opcode instead.

------------------------------------------------------------------------------
*areson*
areson	~

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

Description		~

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

Syntax		~

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

Initialization		~

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

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

Performance		~

ar -- the output signal at audio rate.

asig -- the input signal at audio rate.

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

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

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

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

Examples		~

Here is an example of the areson opcode. It uses the files areson.orc and
areson.sco.

Example 1. Example of the areson opcode.

 /* areson.orc */
 ; Initialize the global variables.
 sr = 22050
 kr = 2205
 ksmps = 10
 nchnls = 1

 ; Instrument #1 - an unfiltered noise waveform.
 instr 1
; Generate a white noise signal.
asig rand 20000

out asig
 endin

 ; Instrument #2 - a filtered noise waveform.
 instr 2
; Generate a white noise signal.
asig rand 20000

; Filter it using the areson opcode.
kcf init 1000
kbw init 100
afilt areson asig, kcf, kbw

; Clip the filtered signal's amplitude to 85 dB.
a1 clip afilt, 2, ampdb(85)
out a1
 endin
 /* areson.orc */

 /* areson.sco */
 ; Play Instrument #1 for two seconds.
 i 1 0 2
 ; Play Instrument #2 for two seconds.
 i 2 2 2
 e
 /* areson.sco */

See Also		~

|aresonk| aresonk, |atone| atone, |atonek| atonek, |port| port, |portk|
portk, |reson| reson, |resonk| resonk, |tone| tone, |tonek| tonek

------------------------------------------------------------------------------
*aresonk*
aresonk	~

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

Description		~

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

Syntax		~

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

Initialization		~

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

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

Performance		~

kr -- the output signal at control-rate.

ksig -- the input signal at control-rate.

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

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

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

See Also		~

|areson| areson, |atone| atone, |atonek| atonek, |port| port, |portk| portk,
|reson| reson, |resonk| resonk, |tone| tone, |tonek| tonek

------------------------------------------------------------------------------
*atone*
atone	~

atone --  A notch filter whose transfer functions are the complements of the
tone opcode.

Description		~

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

Syntax		~

ar atone asig, khp [, iskip]

Initialization		~

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

Performance		~

ar -- the output signal at audio rate.

asig -- the input signal at audio rate.

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

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

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

Examples		~

Here is an example of the atone opcode. It uses the files atone.orc and
atone.sco.

Example 1. Example of the atone opcode.

 /* atone.orc */
 ; Initialize the global variables.
 sr = 22050
 kr = 2205
 ksmps = 10
 nchnls = 1

 ; Instrument #1 - an unfiltered noise waveform.
 instr 1
; Generate a white noise signal.
asig rand 20000

out asig
 endin

 ; Instrument #2 - a filtered noise waveform.
 instr 2
; Generate a white noise signal.
asig rand 20000

; Filter it using the atone opcode.
khp init 2000
afilt atone asig, khp

; Clip the filtered signal's amplitude to 85 dB.
a1 clip afilt, 2, ampdb(85)
out a1
 endin
 /* atone.orc */

 /* atone.sco */
 ; Play Instrument #1 for two seconds.
 i 1 0 2
 ; Play Instrument #2 for two seconds.
 i 2 2 2
 e
 /* atone.sco */

See Also		~

|areson| areson, |aresonk| aresonk, |atonek| atonek, |port| port, |portk|
portk, |reson| reson, |resonk| resonk, |tone| tone, |tonek| tonek

------------------------------------------------------------------------------
*atonek*
atonek	~

atonek --  A notch filter whose transfer functions are the complements of the
tone opcode.

Description		~

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

Syntax		~

kr atonek ksig, khp [, iskip]

Initialization		~

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

Performance		~

kr -- the output signal at control-rate.

ksig -- the input signal at control-rate.

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

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

See Also		~

|areson| areson, |aresonk| aresonk, |atone| atone, |port| port, |portk|
portk, |reson| reson, |resonk| resonk, |tone| tone, |tonek| tonek

------------------------------------------------------------------------------
*atonex*
atonex	~

atonex --  Emulates a stack of filters using the atone opcode.

Description		~

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

Syntax		~

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

Initialization		~

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

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

Performance		~

asig -- input signal

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

See Also		~

|resonx| resonx, |tonex| tonex

Credits		~

Author: Gabriel Maldonado (adapted by John ffitch) 
Italy                                              

New in Csound version 3.49

------------------------------------------------------------------------------
*atrirand*
atrirand	~

atrirand --  Deprecated.

Description		~

Deprecated as of version 3.49. Use the |trirand| trirand opcode instead.

------------------------------------------------------------------------------
*aunirand*
aunirand	~

aunirand --  Deprecated.

Description		~

Deprecated as of version 3.49. Use the |unirand| unirand opcode instead.

------------------------------------------------------------------------------
*aweibull*
aweibull	~

aweibull --  Deprecated.

Description		~

Deprecated as of version 3.49. Use the |weibull| weibull opcode instead.

------------------------------------------------------------------------------
*babo*
babo	~

babo --  A physical model reverberator.

Description		~

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

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

Syntax		~

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

Initialization		~

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

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

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

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

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

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

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

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

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

Performance		~

asig -- the input signal

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

Examples		~

Here is a simple example of the babo opcode. It uses the files babo.orc,
babo.sco, and beats.wav.

Example 1. A simple example of the babo opcode.

 /* babo.orc */
 /* Written by Nicola Bernardini */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 2

 ; minimal babo instrument
 ;
 instr 1
     ix     = p4  ; x position of source
     iy     = p5  ; y position of source
     iz     = p6  ; z position of source
     ixsize = p7  ; width  of the resonator
     iysize = p8  ; depth  of the resonator
     izsize = p9  ; height of the resonator

 ainput soundin "beats.wav"

 al,ar  babo    ainput*0.7, ix, iy, iz, ixsize, iysize, izsize

     outs    al,ar
 endin
 /* babo.orc */

 /* babo.sco */
 /* Written by Nicola Bernardini */
 ; simple babo usage:
 ;
 ;p4     : x position of source
 ;p5     : y position of source
 ;p6     : z position of source
 ;p7     : width  of the resonator
 ;p8     : depth  of the resonator
 ;p9     : height of the resonator
 ;
 i  1  0  10 6  4  3    14.39 11.86 10
 ;           ^^^^^^^    ^^^^^^^^^^^^^^
 ;           |||||||    ++++++++++++++: optimal room dims according to
 ;           |||||||                    Milner and Bernard JASA 85(2), 1989
 ;           +++++++++: source position
 e
 /* babo.sco */

Here is an advanced example of the babo opcode. It uses the files
babo_expert.orc, babo_expert.sco, and beats.wav.

Example 2. An advanced example of the babo opcode.

 /* babo_expert.orc */
 /* Written by Nicola Bernardini */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 2

 ; full blown babo instrument with movement
 ;
 instr 2
ixstart = p4   ; start x position of source (left-right)
ixend   = p7   ; end   x position of source
iystart = p5   ; start y position of source (front-back)
iyend   = p8   ; end   y position of source
izstart = p6   ; start z position of source (up-down)
izend   = p9  ; end   z position of source
ixsize  = p10  ; width  of the resonator
iysize  = p11  ; depth  of the resonator
izsize  = p12  ; height of the resonator
idiff   = p13  ; diffusion coefficient
iexpert = p14  ; power user values stored in this function

 ainput    soundin "beats.wav"
 ksource_x line    ixstart, p3, ixend
 ksource_y line    iystart, p3, iyend
 ksource_z line    izstart, p3, izend

 al,ar     babo    ainput*0.7, ksource_x, ksource_y, ksource_z, ixsize, iysize, izsize, idiff, iexpert

        outs    al,ar
 endin
 /* babo_expert.orc */

 /* babo_expert.sco */
 /* Written by Nicola Bernardini */
 ; full blown instrument
 ;p4         : start x position of source (left-right)
 ;p5         : end   x position of source
 ;p6         : start y position of source (front-back)
 ;p7         : end   y position of source
 ;p8         : start z position of source (up-down)
 ;p9         : end   z position of source
 ;p10        : width  of the resonator
 ;p11        : depth  of the resonator
 ;p12        : height of the resonator
 ;p13        : diffusion coefficient
 ;p14        : power user values stored in this function

 ;         decay  hidecay rx ry rz rdistance direct early_diff
 f1  0 8 -2  0.95   0.95   0  0  0    0.3     0.5      0.8  ; brighter
 f2  0 8 -2  0.95   0.5    0  0  0    0.3     0.5      0.8  ; default (to be set as)
 f3  0 8 -2  0.95   0.01   0  0  0    0.3     0.5      0.8  ; darker
 f4  0 8 -2  0.95   0.7    0  0  0    0.3     0.1      0.4  ; to hear the effect of diffusion
 f5  0 8 -2  0.9    0.5    0  0  0    0.3     2.0      0.98 ; to hear the movement
 f6  0 8 -2  0.99   0.1    0  0  0    0.3     0.5      0.8  ; default vals
 ;        ^
 ;         ----- gen. number: negative to avoid rescaling

 i2 0 10  6  4  3   6   4  3  14.39  11.86  10    1  6 ; defaults
 i2 +  4  6  4  3   6   4  3  14.39  11.86  10    1  1 ; hear brightness 1
 i2 +  4  6  4  3  -6  -4  3  14.39  11.86  10    1  2 ; hear brightness 2
 i2 +  4  6  4  3  -6  -4  3  14.39  11.86  10    1  3 ; hear brightness 3
 i2 +  3 .6 .4 .3 -.6 -.4 .3  1.439  1.186  1.0 0.0  4 ; hear diffusion 1
 i2 +  3 .6 .4 .3 -.6 -.4 .3  1.439  1.186  1.0 1.0  4 ; hear diffusion 2
 i2 +  4 12  4  3 -12  -4 -3  24.39  21.86  20    1  5 ; hear movement
 ;
 i2 +  4  6  4  3   6   4  3  14.39  11.86   10   1  1 ; hear brightness 1
 i2 +  4  6  4  3  -6  -4  3  14.39  11.86   10   1  2 ; hear brightness 2
 i2 +  4  6  4  3  -6  -4  3  14.39  11.86   10   1  3 ; hear brightness 3
 i2 +  3 .6 .4 .3 -.6 -.4 .3  1.439  1.186  1.0 0.0  4 ; hear diffusion 1
 i2 +  3 .6 .4 .3 -.6 -.4 .3  1.439  1.186  1.0 1.0  4 ; hear diffusion 2
 i2 +  4 12  4  3 -12  -4 -3  24.39  21.86   20   1  5 ; hear movement
 ;       ^^^^^^^^^^^^^^^^^^^  ^^^^^^^^^^^^^^^^^   ^  ^
 ;       |||||||||||||||||||  |||||||||||||||||   |   --: expert values function
 ;       |||||||||||||||||||  |||||||||||||||||   +--: diffusion
 ;       |||||||||||||||||||  ----------------: optimal room dims according to Milner and Bernard JASA 85(2), 1989
 ;       |||||||||||||||||||
 ;       --------------------: source position start and end
 e
 /* babo_expert.sco */

Credits		~

Author: Paolo Filippi 
Padova, Italy         
1999                  

Nicola Bernardini 
Rome, Italy       
2000              

New in Csound version 4.09

------------------------------------------------------------------------------
*balance*
balance	~

balance --  Adjust one audio signal according to the values of another.

Description		~

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

Syntax		~

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

Initialization		~

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

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

Performance		~

asig -- input audio signal

acomp -- the comparator signal

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

Examples		~

Here is an example of the balance opcode. It uses the files balance.orc and
balance.sco.

Example 1. Example of the balance opcode.

 /* balance.orc */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Generate a band-limited pulse train.
asrc buzz 30000, 440, sr/440, 1

; Send the source signal through 2 filters.
a1 reson asrc, 1000, 100      
a2 reson a1, 3000, 500

; Balance the filtered signal with the source.
afin balance a2, asrc

out afin
 endin
 /* balance.orc */

 /* balance.sco */
 ; Table #1, a sine wave.
 f 1 0 16384 10 1

 ; Play Instrument #1 for two seconds.
 i 1 0 2
 e
 /* balance.sco */

See Also		~

|gain| gain, |rms| rms

------------------------------------------------------------------------------
*bamboo*
bamboo	~

bamboo --  Semi-physical model of a bamboo sound.

Description		~

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

Syntax		~

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

Initialization		~

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

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

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

damping_amount = 0.9999 + (idamp * 0.002)

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

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

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

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

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

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

Performance		~

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

Examples		~

Here is an example of the bamboo opcode. It uses the files bamboo.orc and
bamboo.sco.

Example 1. Example of the bamboo opcode.

 /* bamboo.orc */
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 instr 01  ;example of bamboo
 a1  bamboo p4, 0.01
  out a1
  endin
 /* bamboo.orc */

 /* bamboo.sco */
 i1 0 1 20000
 e
 /* bamboo.sco */

See Also		~

|dripwater| dripwater, |guiro| guiro, |sleighbells| sleighbells, |tambourine|
tambourine

Credits		~

Author: Perry Cook, part of the PhISEM (Physically Informed Stochastic Event  
Modeling)                                                                     
Adapted by John ffitch                                                        
University of Bath, Codemist Ltd.                                             
Bath, UK                                                                      

New in Csound version 4.07

Added notes by Rasmus Ekman on May 2002.

------------------------------------------------------------------------------
*bbcutm*
bbcutm	~

bbcutm --  Generates breakbeat-style cut-ups of a mono audio stream.

Description		~

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

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

3+ 3R + 2

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

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

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

Syntax		~

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

Initialization		~

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

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

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

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

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

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

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

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

Performance		~

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

Examples		~

Here is a simple example of the bbcutm opcode. It uses the files bbcutm.orc,
bbcutm.sco, and beats.wav.

Example 1. A simple example of the bbcutm opcode.

 /* bbcutm.orc */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1 - Play an audio file normally.
 instr 1
asource soundin "beats.wav"
out asource
 endin

 ; Instrument #2 - Cut-up an audio file.
 instr 2
asource soundin "beats.wav"

ibps = 4
isubdiv = 8
ibarlength = 4
iphrasebars = 1
inumrepeats = 2

a1 bbcutm asource, ibps, isubdiv, ibarlength, iphrasebars, inumrepeats

out a1
 endin
 /* bbcutm.orc */

 /* bbcutm.sco */
 ; Play Instrument #1 for two seconds.
 i 1 0 2
 ; Play Instrument #2 for two seconds.
 i 2 3 2
 e
 /* bbcutm.sco */

Here are some more advanced examples...

Example 2. First steps- mono and stereo versions

 <CsoundSynthesizer>
 <CsInstruments>
 sr        =         44100
 kr        =         4410
 ksmps     =         10
 nchnls    =         2
 instr 1
  asource diskin "break7.wav",1,0,1   ; a source breakbeat sample, wraparound lest it stop!
  ; cuts in eighth notes per 4/4 bar, up to 4 bar phrases, up to 1
  ; repeat in total (standard use) rare stuttering at 16 note speed,
  ; no enveloping
  asig bbcutm asource, 2.6937, 8,4,4,1,   2,0.1,0
  outs        asig,asig
 endin
 instr 2 ;stereo version
 asource1,asource2 diskin "break7stereo.wav",1,0,1    ; a source breakbeat sample, wraparound lest it stop!
; cuts in eighth notes per 4/4 bar, up to 4 bar phrases, up to 1
; repeat in total (standard use) rare stuttering at 16 note speed,
; no enveloping
asig1,asig2 bbcuts asource1, asource2, 2.6937, 8,4,4,1,   2,0.1,0
outs  asig1,asig2
 endin
 </CsInstruments>
 <CsScore>
 i1 0 10
 i2 11 10
 e
 </CsScore>
 </CsoundSynthesizer>

Example 3. Multiple simultaneous synchronised breaks

 <CsoundSynthesizer>
 <CsInstruments>
 sr        =         44100
 kr        =         4410
 ksmps     =         10
 nchnls    =         1
 instr 1
ibps    = 2.6937
iplaybackspeed = ibps/p5
asource diskin p4,iplaybackspeed,0,1
asig bbcutm asource, 2.6937, p6,4,4,p7,   2,0.1,1
out   asig
 endin
 </CsInstruments>
 <CsScore>
 ;   source      bps cut repeats
 i1 0 10 "break1.wav" 2.3 8   2  //2.3 is the source original tempo
 i1 0 10 "break2.wav" 2.4 8   3
 i1 0 10 "break3.wav" 2.5 16  4
 e
 </CsScore>
 </CsoundSynthesizer>

Example 4. Cutting up any old audio- much more interesting noises than this
should be possible!

 <CsoundSynthesizer>
 <CsInstruments>
 sr        =         44100
 kr        =         4410
 ksmps     =         10
 nchnls    =         1
 instr 1
asource oscil 20000,70,1
; ain,bps,subdiv,barlength,phrasebars,numrepeats,
;stutterspeed,stutterchance,envelopingon
asig bbcutm asource, 2, 32,1,1,2, 4,0.6,1
outs  asig
 endin
 </CsInstruments>
 <CsScore>
 f1 0 256 10 1
 i1 0 10
 e
 </CsScore>
 </CsoundSynthesizer>

Example 5. Constant stuttering- faked, not possible since can only stutter in
last half bar could make extra stuttering option parameter

 <CsoundSynthesizer>
 <CsInstruments>
 sr        =         44100
 kr        =         4410
 ksmps     =         10
 nchnls    =         1
 instr 1
asource diskin "break7.wav",1,0,1
;16th note cuts- but cut size 2 over half a beat.
;each half beat will eiather survive intact or be turned into
;the first sixteenth played twice in succession
asig bbcutm asource,2.6937,2,0.5,1,2, 2,1.0,0
outs  asig
 endin
 </CsInstruments>
 <CsScore>
 i1 0 30
 e
 </CsScore>
 </CsoundSynthesizer>

See Also		~

|bbcuts| bbcuts

Credits		~

Author: Nick Collins 
London               
August 2001          

New in version 4.13

------------------------------------------------------------------------------
*bbcuts*
bbcuts	~

bbcuts --  Generates breakbeat-style cut-ups of a stereo audio stream.

Description		~

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

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

3+ 3R + 2

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

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

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

Syntax		~

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

Initialization		~

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

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

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

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

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

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

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

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

Performance		~

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

Examples		~

See the advanced examples for the |bbcutm| bbcutm opcode.

See Also		~

|bbcutm| bbcutm

Credits		~

Author: Nick Collins 
London               
August 2001          

New in version 4.13

------------------------------------------------------------------------------
*betarand*
betarand	~

betarand --  Beta distribution random number generator (positive values
only).

Description		~

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

Syntax		~

ar betarand krange, kalpha, kbeta

ir betarand krange, kalpha, kbeta

kr betarand krange, kalpha, kbeta

Performance		~

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

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

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

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

For more detailed explanation of these distributions, see:

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

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

Examples		~

Here is an example of the betarand opcode. It uses the files betarand.orc and
betarand.sco.

Example 1. Example of the betarand opcode.

 /* betarand.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Generate a number between 0 and 1 with a
; uniform distribution.
; krange = 1
; kalpha = 1
; kbeta = 1

i1 betarand 1, 1, 1

print i1
 endin
 /* betarand.orc */

 /* betarand.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* betarand.sco */

Its output should include lines like:

 instr 1:  i1 = 24583.412

See Also		~

|bexprnd| bexprnd, |cauchy| cauchy, |exprand| exprand, |gauss| gauss,
|linrand| linrand, |pcauchy| pcauchy, |poisson| poisson, |trirand| trirand,
|unirand| unirand, |weibull| weibull

Credits		~

Author: Paris Smaragdis 
MIT, Cambridge          
1995                    

------------------------------------------------------------------------------
*bexprnd*
bexprnd	~

bexprnd --  Exponential distribution random number generator.

Description		~

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

Syntax		~

ar bexprnd krange

ir bexprnd krange

kr bexprnd krange

Performance		~

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

For more detailed explanation of these distributions, see:

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

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

Examples		~

Here is an example of the bexprnd opcode. It uses the files bexprnd.orc and
bexprnd.sco.

Example 1. Example of the bexprnd opcode.

 /* bexprnd.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Generate a random number between -1 and 1.
; krange = 1

i1 bexprnd 1

print i1
 endin
 /* bexprnd.orc */

 /* bexprnd.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* bexprnd.sco */

Its output should include lines like:

 instr 1:  i1 = 1.141

See Also		~

|betarand| betarand, |cauchy| cauchy, |exprand| exprand, |gauss| gauss,
|linrand| linrand, |pcauchy| pcauchy, |poisson| poisson, |trirand| trirand,
|unirand| unirand, |weibull| weibull

Credits		~

Author: Paris Smaragdis 
MIT, Cambridge          
1995                    

------------------------------------------------------------------------------
*biquad*
biquad	~

biquad --  A sweepable general purpose biquadratic digital filter.

Description		~

A sweepable general purpose biquadratic digital filter.

Syntax		~

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

Initialization		~

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

Performance		~

asig -- input signal

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

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

This filter has the following frequency response:

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

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

Examples		~

Here is an example of the biquad opcode. It uses the files biquad.orc and
biquad.sco.

Example 1. Example of the biquad opcode.

 /* biquad.orc */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 2

 ; Instrument #1.
 instr 1
; Get the values from the score.
idur = p3
iamp = p4
icps = cpspch(p5)
kfco = p6
krez = p7

; Calculate the biquadratic filter's coefficients
kfcon = 2*3.14159265*kfco/sr
kalpha = 1-2*krez*cos(kfcon)*cos(kfcon)+krez*krez*cos(2*kfcon)
kbeta = krez*krez*sin(2*kfcon)-2*krez*cos(kfcon)*sin(kfcon)
kgama = 1+cos(kfcon)
km1 = kalpha*kgama+kbeta*sin(kfcon)
km2 = kalpha*kgama-kbeta*sin(kfcon)
kden = sqrt(km1*km1+km2*km2)
kb0 = 1.5*(kalpha*kalpha+kbeta*kbeta)/kden
kb1 = kb0
kb2 = 0
ka0 = 1
ka1 = -2*krez*cos(kfcon)
ka2 = krez*krez

; Generate an input signal.
axn vco 1, icps, 1

; Filter the input signal.
ayn biquad axn, kb0, kb1, kb2, ka0, ka1, ka2
outs ayn*iamp/2, ayn*iamp/2
 endin
 /* biquad.orc */

 /* biquad.sco */
 ; Table #1, a sine wave.
 f 1 0 16384 10 1

 ;    Sta  Dur  Amp    Pitch Fco   Rez
 i 1  0.0  1.0  20000  6.00  1000  .8
 i 1  1.0  1.0  20000  6.03  2000  .95
 e
 /* biquad.sco */

See Also		~

|biquada| biquada, |moogvcf| moogvcf, |rezzy| rezzy

Credits		~

Author: Hans Mikelson 
October 1998          

New in Csound version 3.49

------------------------------------------------------------------------------
*biquada*
biquada	~

biquada --  A sweepable general purpose biquadratic digital filter with
a-rate parameters.

Description		~

A sweepable general purpose biquadratic digital filter.

Syntax		~

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

Initialization		~

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

Performance		~

asig -- input signal

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

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

This filter has the following frequency response:

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

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

See Also		~

|biquad| biquad

Credits		~

Author: Hans Mikelson 
October 1998          

New in Csound version 3.49

------------------------------------------------------------------------------
*birnd*
birnd	~

birnd --  Returns a random number in a bi-polar range.

Description		~

Returns a random number in a bi-polar range.

Syntax		~

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

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

Performance		~

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

Examples		~

Here is an example of the birnd opcode. It uses the files birnd.orc and
birnd.sco.

Example 1. Example of the birnd opcode.

 /* birnd.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Generate a random number from -1 to 1.
i1 = birnd(1)
print i1
 endin
 /* birnd.orc */

 /* birnd.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 ; Play Instrument #1 for one second.
 i 1 1 1
 e
 /* birnd.sco */

Its output should include lines like:

 instr 1:  i1 = 0.947
 instr 1:  i1 = -0.721

See Also		~

|rnd| rnd

Credits		~

Author: Barry L. Vercoe   
MIT                       
Cambridge, Massachussetts 
1997                      

------------------------------------------------------------------------------
*bqrez*
bqrez	~

bqrez --  A second-order multi-mode filter.

Description		~

A second-order multi-mode filter.

Syntax		~

ar bqrez asig, xfco, xres [, imode]

Initialization		~

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

  * 0 = low-pass (default)

  * 1 = high-pass

  * 2 = band-pass

  * 3 = band-reject

  * 4 = all-pass

Performance		~

ar -- output audio signal.

asig -- input audio signal.

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

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

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

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

Examples		~

Here is an example of the bqrez opcode. It uses the files bqrez.orc and
bqrez.sco.

Example 1. Example of the bqrez opcode borrowed from the "rezzy" opcode in
Kevin Conder's manual.

 /* bqrez.orc */
 /* Written by Matt Gerassimof from example by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Use a nice sawtooth waveform.
asig vco 16000, 220, 1

; Vary the filter-cutoff frequency from .2 to 2 KHz.
kfco line 200, p3, 2000

; Set the resonance amount.
kres init 0.99

a1 bqrez asig, kfco, kres

out a1
 endin
 /* bqrez.orc */

 /* bqrez.sco */
 /* Written by Matt Gerassimof from example by Kevin Conder */
 ; Table #1, a sine wave for the vco opcode.
 f 1 0 16384 10 1

 ; Play Instrument #1 for three seconds.
 i 1 0 3
 e
 /* bqrez.sco */

See Also		~

|biquad| biquad, |moogvcf| moogvcf, |rezzy| rezzy

Credits		~

Author: Matt Gerassimoff  
New in version 4.32       
Written in November 2002. 

------------------------------------------------------------------------------
*butbp*
butbp	~

butbp --  Same as the butterbp opcode.

Description		~

Same as the |butterbp| butterbp opcode.

Syntax		~

ar butbp asig, kfreq, kband [, iskip]

------------------------------------------------------------------------------
*butbr*
butbr	~

butbr --  Same as the butterbr opcode.

Description		~

Same as the |butterbr| butterbr opcode.

Syntax		~

ar butbr asig, kfreq, kband [, iskip]

------------------------------------------------------------------------------
*buthp*
buthp	~

buthp --  Same as the butterhp opcode.

Description		~

Same as the |butterhp| butterhp opcode.

Syntax		~

ar buthp asig, kfreq [, iskip]

------------------------------------------------------------------------------
*butlp*
butlp	~

butlp --  Same as the butterlp opcode.

Description		~

Same as the |butterlp| butterlp opcode.

Syntax		~

ar butlp asig, kfreq [, iskip]

------------------------------------------------------------------------------
*butterbp*
butterbp	~

butterbp --  A band-pass Butterworth filter.

Description		~

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

Syntax		~

ar butterbp asig, kfreq, kband [, iskip]

Initialization		~

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

Performance		~

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

asig -- Input signal to be filtered.

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

kband -- Bandwidth of the bandpass and bandreject filters.

Examples		~

Here is an example of the butterbp opcode. It uses the files butterbp.orc and
butterbp.sco.

Example 1. Example of the butterbp opcode.

 /* butterbp.orc */
 ; Initialize the global variables.
 sr = 22050
 kr = 2205
 ksmps = 10
 nchnls = 1

 ; Instrument #1 - an unfiltered noise waveform.
 instr 1
; White noise signal
asig rand 22050

out asig
 endin

 ; Instrument #2 - a filtered noise waveform.
 instr 2
; White noise signal
asig rand 22050

; Filter it, passing only 1950 to 2050 Hz.
abp butterbp asig, 2000, 100

out abp
 endin
 /* butterbp.orc */

 /* butterbp.sco */
 ; Play Instrument #1 for two seconds.
 i 1 0 2
 ; Play Instrument #2 for two seconds.
 i 2 2 2
 e
 /* butterbp.sco */

See Also		~

|butterbr| butterbr, |butterhp| butterhp, |butterlp| butterlp

Credits		~

Author: Paris Smaragdis 
MIT, Cambridge          
1995                    

------------------------------------------------------------------------------
*butterbr*
butterbr	~

butterbr --  A band-reject Butterworth filter.

Description		~

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

Syntax		~

ar butterbr asig, kfreq, kband [, iskip]

Initialization		~

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

Performance		~

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

asig -- Input signal to be filtered.

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

kband -- Bandwidth of the bandpass and bandreject filters.

Examples		~

Here is an example of the butterbr opcode. It uses the files butterbr.orc and
butterbr.sco.

Example 1. Example of the butterbr opcode.

 /* butterbr.orc */
 ; Initialize the global variables.
 sr = 22050
 kr = 2205
 ksmps = 10
 nchnls = 1

 ; Instrument #1 - an unfiltered noise waveform.
 instr 1
; White noise signal
asig rand 22050

out asig
 endin

 ; Instrument #2 - a filtered noise waveform.
 instr 2
; White noise signal
asig rand 22050

; Filter it, cutting 2000 to 6000 Hz.
abr butterbr asig, 4000, 2000

out abr
 endin
 /* butterbr.orc */

 /* butterbr.sco */
 ; Play Instrument #1 for two seconds.
 i 1 0 2
 ; Play Instrument #2 for two seconds.
 i 2 2 2
 e
 /* butterbr.sco */

See Also		~

|butterbp| butterbp, |butterhp| butterhp, |butterlp| butterlp

Credits		~

Author: Paris Smaragdis 
MIT, Cambridge          
1995                    

------------------------------------------------------------------------------
*butterhp*
butterhp	~

butterhp --  A high-pass Butterworth filter.

Description		~

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

Syntax		~

ar butterhp asig, kfreq [, iskip]

Initialization		~

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

Performance		~

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

asig -- Input signal to be filtered.

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

Examples		~

Here is an example of the butterhp opcode. It uses the files butterhp.orc and
butterhp.sco.

Example 1. Example of the butterhp opcode.

 /* butterhp.orc */
 ; Initialize the global variables.
 sr = 22050
 kr = 2205
 ksmps = 10
 nchnls = 1

 ; Instrument #1 - an unfiltered noise waveform.
 instr 1
; White noise signal
asig rand 22050

out asig
 endin

 ; Instrument #2 - a filtered noise waveform.
 instr 2
; White noise signal
asig rand 22050

; Filter it, passing frequencies above 250 Hz.
ahp butterhp asig, 250

out ahp
 endin
 /* butterhp.orc */

 /* butterhp.sco */
 ; Play Instrument #1 for two seconds.
 i 1 0 2
 ; Play Instrument #2 for two seconds.
 i 2 2 2
 e
 /* butterhp.sco */

See Also		~

|butterbp| butterbp, |butterbr| butterbr, |butterlp| butterlp

Credits		~

Author: Paris Smaragdis 
MIT, Cambridge          
1995                    

------------------------------------------------------------------------------
*butterlp*
butterlp	~

butterlp --  A low-pass Butterworth filter.

Description		~

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

Syntax		~

ar butterlp asig, kfreq [, iskip]

Initialization		~

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

Performance		~

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

asig -- Input signal to be filtered.

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

Examples		~

Here is an example of the butterlp opcode. It uses the files butterlp.orc and
butterlp.sco.

Example 1. Example of the butterlp opcode.

 /* butterlp.orc */
 ; Initialize the global variables.
 sr = 22050
 kr = 2205
 ksmps = 10
 nchnls = 1

 ; Instrument #1 - an unfiltered noise waveform.
 instr 1
; White noise signal
asig rand 22050

out asig
 endin

 ; Instrument #2 - a filtered noise waveform.
 instr 2
; White noise signal
asig rand 22050

; Filter it, cutting frequencies above 1 KHz.
alp butterlp asig, 1000

out alp
 endin
 /* butterlp.orc */

 /* butterlp.sco */
 ; Play Instrument #1 for two seconds.
 i 1 0 2
 ; Play Instrument #2 for two seconds.
 i 2 2 2
 e
 /* butterlp.sco */

See Also		~

|butterbp| butterbp, |butterbr| butterbr, |butterhp| butterhp

Credits		~

Author: Paris Smaragdis 
MIT, Cambridge          
1995                    

------------------------------------------------------------------------------
*button*
button	~

button --  Sense on-screen controls.

Description		~

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

Syntax		~

kr button knum

Performance		~

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

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

See Also		~

|checkbox| checkbox

Credits		~

Author: John ffitch                
University of Bath, Codemist. Ltd. 
Bath, UK                           
September 2000                     

New in Csound version 4.08

------------------------------------------------------------------------------
*buzz*
buzz	~

buzz --  Output is a set of harmonically related sine partials.

Description		~

Output is a set of harmonically related sine partials.

Syntax		~

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

Initialization		~

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

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

Performance		~

xamp -- amplitude

xcps -- frequency in cycles per second

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

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

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

Although both knh and klh may be varied during performance, their internal
values are necessarily integer and may cause "pops" due to discontinuities in
the output; kr, however, can be varied during performance to good effect.
Both buzz and gbuzz can be amplitude- and/or frequency-modulated by either
control or audio signals.

N.B. These two units have their analogs in |gen11| GEN11, in which the same
set of cosines can be stored in a function table for sampling by an
oscillator. Although computationally more efficient, the stored pulse train
has a fixed spectral content, not a time-varying one as above.

Examples		~

Here is an example of the buzz opcode. It uses the files buzz.orc and
buzz.sco.

Example 1. Example of the buzz opcode.

 /* buzz.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
kamp = 20000
kcps = 440
knh = 3
ifn = 1

a1 buzz kamp, kcps, knh, ifn
out a1
 endin
 /* buzz.orc */

 /* buzz.sco */
 /* Written by Kevin Conder */
 ; Table #1, a sine wave.
 f 1 0 16384 10 1

 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* buzz.sco */

See Also		~

|gbuzz| gbuzz

------------------------------------------------------------------------------
*cabasa*
cabasa	~

cabasa --  Semi-physical model of a cabasa sound.

Description		~

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

Syntax		~

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

Initialization		~

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

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

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

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

damping_amount = 0.998 + (idamp * 0.002)

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

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

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

Examples		~

Here is an example of the cabasa opcode. It uses the files cabasa.orc and
cabasa.sco.

Example 1. Example of the cabasa opcode.

 /* cabasa.orc */
 ;orchestra ---------------

sr =           44100
kr =            4410
ksmps =              10
nchnls =               1

        instr 01                  ;an example of a cabasa
 a1      cabasa p4, 0.01
        out a1
        endin
 /* cabasa.orc */

 /* cabasa.sco */
 ;score -------------------

 i1 0 1 26000
 e
 /* cabasa.sco */

See Also		~

|crunch| crunch, |sandpaper| sandpaper, |sekere| sekere, |stix| stix

Credits		~

Author: Perry Cook, part of the PhISEM (Physically Informed Stochastic Event  
Modeling)                                                                     
Adapted by John ffitch                                                        
University of Bath, Codemist Ltd.                                             
Bath, UK                                                                      

New in Csound version 4.07

Added notes by Rasmus Ekman on May 2002.

------------------------------------------------------------------------------
*cauchy*
cauchy	~

cauchy --  Cauchy distribution random number generator.

Description		~

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

Syntax		~

ar cauchy kalpha

ir cauchy kalpha

kr cauchy kalpha

Performance		~

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

For more detailed explanation of these distributions, see:

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

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

Examples		~

Here is an example of the cauchy opcode. It uses the files cauchy.orc and
cauchy.sco.

Example 1. Example of the cauchy opcode.

 /* cauchy.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Generate a random number, spread from 10.
; kalpha = 10

i1 cauchy 10

print i1
 endin
 /* cauchy.orc */

 /* cauchy.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* cauchy.sco */

Its output should include lines like:

 instr 1:  i1 = -0.106

See Also		~

|betarand| betarand, |bexprnd| bexprnd, |exprand| exprand, |gauss| gauss,
|linrand| linrand, |pcauchy| pcauchy, |poisson| poisson, |trirand| trirand,
|unirand| unirand, |weibull| weibull

Credits		~

Author: Paris Smaragdis 
MIT, Cambridge          
1995                    

------------------------------------------------------------------------------
*cent*
cent	~

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

Description		~

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

Syntax		~

cent(x)

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

Initialization		~

x -- a value expressed in cents.

Performance		~

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

Examples		~

Here is an example of the cent opcode. It uses the files cent.orc and
cent.sco.

Example 1. Example of the cent opcode.

 /* cent.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; The root note is A above middle-C (440 Hz)
iroot = 440

; Raise the root note by 300 cents to C.
icents = 300

; Calculate the new note.
ifactor = cent(icents)
inew = iroot * ifactor

; Print out of all of the values.
print iroot
print ifactor
print inew
 endin
 /* cent.orc */

 /* cent.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* cent.sco */

Its output should include lines like:

 instr 1:  iroot = 440.000
 instr 1:  ifactor = 1.189
 instr 1:  inew = 523.229

See Also		~

|db| db, |octave| octave, |semitone| semitone

Credits		~

New in version 4.16

------------------------------------------------------------------------------
*cggoto*
cggoto	~

cggoto --  Conditionally transfer control on every pass.

Description		~

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

Syntax		~

cggoto condition, label

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

Examples		~

Here is an example of the cggoto opcode. It uses the files cggoto.orc and
cggoto.sco.

Example 1. Example of the cggoto opcode.

 /* cggoto.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
i1 = 1

; If i1 is equal to one, play a high note.
; Otherwise play a low note.
cggoto (i1 == 1), highnote

 lownote:
a1 oscil 10000, 220, 1
goto playit

 highnote:
a1 oscil 10000, 440, 1
goto playit

 playit:
out a1
 endin
 /* cggoto.orc */

 /* cggoto.sco */
 /* Written by Kevin Conder */
 ; Table #1: a simple sine wave.
 f 1 0 32768 10 1

 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* cggoto.sco */

See Also		~

|cigoto| cigoto, |ckgoto| ckgoto, |cngoto| cngoto, |if| if, |igoto| igoto,
|kgoto| kgoto, |tigoto| tigoto, |timout| timout

Credits		~

Added a note by Jim Aikin.

------------------------------------------------------------------------------
*chanctrl*
chanctrl	~

chanctrl --  Get the current value of a MIDI channel controller.

Description		~

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

Syntax		~

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

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

Initialization		~

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

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

ilow, ihigh -- low and high ranges for mapping

Credits		~

Author: Mike Berry 
Mills College      
May, 1997          

Thanks goes to Rasmus Ekman for pointing out the correct MIDI channel and
controller number ranges.

------------------------------------------------------------------------------
*checkbox*
checkbox	~

checkbox --  Sense on-screen controls.

Description		~

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

Syntax		~

kr checkbox knum

Performance		~

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

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

Examples		~

Here is a simple example of the checkbox opcode. It uses the files
checkbox.orc and checkbox.sco.

Example 1. Simple example of the checkbox opcode.

 /* checkbox.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 44100
 ksmps = 1
 nchnls = 1
 instr 1
; Get the value from the checkbox.
k1 checkbox 1

; If the checkbox is selected then k2=440, otherwise k2=880.
k2 = (k1 == 0 ? 440 : 880)

a1 oscil 10000, k2, 1
out a1
 endin
 /* checkbox.orc */

 /* checkbox.sco */
 /* Written by Kevin Conder */
 ; Just generate a nice, ordinary sine wave.
 f 1 0 32768 10 1

 ; Play Instrument #1 for ten seconds.
 i 1 0 10
 e
 /* checkbox.sco */

See Also		~

|button| button

Credits		~

Author: John ffitch                
University of Bath, Codemist. Ltd. 
Bath, UK                           
September, 2000                    

New in Csound version 4.08

------------------------------------------------------------------------------
*cigoto*
cigoto	~

cigoto --  Conditionally transfer control during the i-time pass.

Description		~

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

Syntax		~

cigoto condition, label

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

Examples		~

Here is an example of the cigoto opcode. It uses the files cigoto.orc and
cigoto.sco.

Example 1. Example of the cigoto opcode.

 /* cigoto.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Get the value of the 4th p-field from the score.
iparam = p4

; If iparam is 1 then play the high note.
; If not then play the low note.
cigoto (iparam ==1), highnote
  igoto lownote

 highnote:
ifreq = 880
goto playit

 lownote:
ifreq = 440
goto playit

 playit:
; Print the values of iparam and ifreq.
print iparam
print ifreq

a1 oscil 10000, ifreq, 1
out a1
 endin
 /* cigoto.orc */

 /* cigoto.sco */
 /* Written by Kevin Conder */
 ; Table #1: a simple sine wave.
 f 1 0 32768 10 1

 ; p4: 1 = high note, anything else = low note
 ; Play Instrument #1 for one second, a low note.
 i 1 0 1 0
 ; Play a Instrument #1 for one second, a high note.
 i 1 1 1 1
 e
 /* cigoto.sco */

Its output should include lines like:

 instr 1:  iparam = 0.000
 instr 1:  ifreq = 440.000
 instr 1:  iparam = 1.000
 instr 1:  ifreq = 880.000

See Also		~

|cggoto| cggoto, |ckgoto| ckgoto, |cngoto| cngoto, |goto| goto, |if| if,
|kgoto| kgoto, |rigoto| rigoto, |tigoto| tigoto, |timout| timout

Credits		~

Added a note by Jim Aikin.

------------------------------------------------------------------------------
*ckgoto*
ckgoto	~

ckgoto --  Conditionally transfer control during the p-time passes.

Description		~

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

Syntax		~

ckgoto condition, label

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

Examples		~

Here is an example of the ckgoto opcode. It uses the files ckgoto.orc and
ckgoto.sco.

Example 1. Example of the ckgoto opcode.

 /* ckgoto.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Change kval linearly from 0 to 2 over
; the period set by the third p-field.
kval line 0, p3, 2

; If kval is greater than or equal to 1 then play the high note.
; If not then play the low note.
ckgoto (kval >= 1), highnote
  kgoto lownote

 highnote:
kfreq = 880
goto playit

 lownote:
kfreq = 440
goto playit

 playit:
; Print the values of kval and kfreq.
printks "kval = %f, kfreq = %f\\n", 1, kval, kfreq

a1 oscil 10000, kfreq, 1
out a1
 endin
 /* ckgoto.orc */

 /* ckgoto.sco */
 /* Written by Kevin Conder */
 ; Table: a simple sine wave.
 f 1 0 32768 10 1

 ; Play Instrument #1 for two seconds.
 i 1 0 2
 e
 /* ckgoto.sco */

Its output should include lines like:

 kval = 0.000000, kfreq = 440.000000
 kval = 0.999732, kfreq = 440.000000
 kval = 1.999639, kfreq = 880.000000

See Also		~

|cggoto| cggoto, |cigoto| cigoto, |cngoto| cngoto, |goto| goto, |if| if,
|igoto| igoto, |tigoto| tigoto, |timout| timout

Credits		~

Added a note by Jim Aikin.

------------------------------------------------------------------------------
*clear*
clear	~

clear --  Zeroes a list of audio signals.

Description		~

clear zeroes a list of audio signals.

Syntax		~

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

Performance		~

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

|vincr| vincr (variable increment) and clear are intended to be used
together. vincr stores the result of the sum of two audio variables into the
first variable itself (which is intended to be used as an accumulator in
polyphony). The accumulator variable can be used for output signal by means
of |fout| fout opcode. After the disk writing operation, the accumulator
variable should be set to zero by means of clear opcode (or it will explode).

Examples		~

See the |fout| fout opcode for an example.

See Also		~

|vincr| vincr

Credits		~

Author: Gabriel Maldonado 
Italy                     
1999                      

New in Csound version 3.56

------------------------------------------------------------------------------
*clfilt*
clfilt	~

clfilt --  Implements low-pass and high-pass filters of different styles.

Description		~

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

Syntax		~

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

Initialization		~

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

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

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

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

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

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

Performance		~

asig -- The input audio signal.

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

Examples		~

Here is an example of the clfilt opcode as a low-pass filter. It uses the
files clfilt_lowpass.orc and clfilt_lowpass.sco.

Example 1. Example of the clfilt opcode as a low-pass filter.

 /* clfilt_lowpass.orc */
 ; Initialize the global variables.
 sr = 22050
 kr = 2205
 ksmps = 10
 nchnls = 1

 ; Instrument #1 - an unfiltered noise waveform.
 instr 1
; White noise signal
asig rand 22050

out asig
 endin

 ; Instrument #2 - a filtered noise waveform.
 instr 2
; White noise signal
asig rand 22050

; Lowpass filter signal asig with a
; 10-pole Butterworth at 500 Hz.
a1 clfilt asig, 500, 0, 10

out a1
 endin
 /* clfilt_lowpass.orc */

 /* clfilt_lowpass.sco */
 ; Play Instrument #1 for two seconds.
 i 1 0 2
 ; Play Instrument #2 for two seconds.
 i 2 2 2
 e
 /* clfilt_lowpass.sco */

Here is an example of the clfilt opcode as a high-pass filter. It uses the
files clfilt_highpass.orc and clfilt_highpass.sco.

Example 2. Example of the clfilt opcode as a high-pass filter.

 /* clfilt_highpass.orc */
 ; Initialize the global variables.
 sr = 22050
 kr = 2205
 ksmps = 10
 nchnls = 1

 ; Instrument #1 - an unfiltered noise waveform.
 instr 1
; White noise signal
asig rand 22050

out asig
 endin

 ; Instrument #2 - a filtered noise waveform.
 instr 2
; White noise signal
asig rand 22050

; Highpass filter signal asig with a 6-pole Chebyshev
; Type I at 20 Hz with 3 dB of passband ripple.
a1 clfilt asig, 20, 1, 6, 1, 3

out a1
 endin
 /* clfilt_highpass.orc */

 /* clfilt_highpass.sco */
 ; Play Instrument #1 for two seconds.
 i 1 0 2
 ; Play Instrument #2 for two seconds.
 i 2 2 2
 e
 /* clfilt_highpass.sco */

Credits		~

Author: Erik Spjut

New in version 4.20

------------------------------------------------------------------------------
*clip*
clip	~

clip --  Clips a signal to a predefined limit.

Description		~

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

Syntax		~

ar clip asig, imeth, ilimit [, iarg]

Initialization		~

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

  * 0 = Bram de Jong method (default)

  * 1 = sine clipping

  * 2 = tanh clipping

ilimit -- limiting value

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

Performance		~

asig -- a-rate input signal

The Bram de Jong method (imeth = 0) applies the algorithm:

 |x| > a:     f(x) = sin(x) * (a+(x-a)/(1+((x-a)/(1-a))2 |x| > 1: f(x) = sin(x) * (a+1)/2

This method requires that asig be normalized to 1.

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

 |x| < limit: f(x) = limit * sin(p*x/(2*limit)) f(x) = limit * sin(x)

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

 |x| < limit: f(x) = limit * tanh(x/limit)/tanh(1) f(x) = limit * sin(x)

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

Examples		~

Here is an example of the clip opcode. It uses the files clip.orc and
clip.sco.

Example 1. Example of the clip opcode.

 /* clip.orc */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Generate a noisy waveform.
arnd rand 44100
; Clip the noisy waveform's amplitude to 20,000
a1 clip arnd, 2, 20000

out a1
 endin
 /* clip.orc */

 /* clip.sco */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* clip.sco */

Credits		~

Author: John ffitch               
University of Bath, Codemist Ltd. 
Bath, UK                          
August, 2000                      

New in Csound version 4.07

------------------------------------------------------------------------------
*clock*
clock	~

clock --  Deprecated.

Description		~

Deprecated. Use the |rtclock| rtclock opcode instead.

------------------------------------------------------------------------------
*clockoff*
clockoff	~

clockoff --  Stops one of a number of internal clocks.

Description		~

Stops one of a number of internal clocks.

Syntax		~

clockoff inum

Initialization		~

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

Performance		~

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

Examples		~

See the |readclock| readclock opcode for an example.

See Also		~

|clockon| clockon, |readclock| readclock

Credits		~

Author: John ffitch              
University of Bath/Codemist Ltd. 
Bath, UK                         
July, 1999                       

New in Csound version 3.56

------------------------------------------------------------------------------
*clockon*
clockon	~

clockon --  Starts one of a number of internal clocks.

Description		~

Starts one of a number of internal clocks.

Syntax		~

clockon inum

Initialization		~

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

Performance		~

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

Examples		~

See the |readclock| readclock opcode for an example.

See Also		~

|clockoff| clockoff, |readclock| readclock

Credits		~

Author: John ffitch              
University of Bath/Codemist Ltd. 
Bath, UK                         
July, 1999                       

New in Csound version 3.56

------------------------------------------------------------------------------
*cngoto*
cngoto	~

cngoto --  Transfers control on every pass when a condition is not true.

Description		~

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

Syntax		~

cngoto condition, label

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

Examples		~

Here is an example of the cngoto opcode. It uses the files cngoto.orc and
cngoto.sco.

Example 1. Example of the cngoto opcode.

 /* cngoto.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Change kval linearly from 0 to 2 over
; the period set by the third p-field.
kval line 0, p3, 2

; If kval *is not* greater than or equal to 1 then play
; the high note. Otherwise, play the low note.
cngoto (kval >= 1), highnote
  kgoto lownote

 highnote:
kfreq = 880
goto playit

 lownote:
kfreq = 440
goto playit

 playit:
; Print the values of kval and kfreq.
printks "kval = %f, kfreq = %f\\n", 1, kval, kfreq

a1 oscil 10000, kfreq, 1
out a1
 endin
 /* cngoto.orc */

 /* cngoto.sco */
 /* Written by Kevin Conder */
 ; Table: a simple sine wave.
 f 1 0 32768 10 1

 ; Play Instrument #1 for two seconds.
 i 1 0 2
 e
 /* cngoto.sco */

Its output should include lines like:

 kval = 0.000000, kfreq = 880.000000
 kval = 0.999732, kfreq = 880.000000
 kval = 1.999639, kfreq = 440.000000

See Also		~

|cggoto| cggoto, |cigoto| cigoto, |ckgoto| ckgoto, |goto| goto, |if| if,
|igoto| igoto, |tigoto| tigoto, |timout| timout

Credits		~

New in version 4.21

------------------------------------------------------------------------------
*comb*
comb	~

comb --  Reverberates an input signal with a "colored" frequency response.

Description		~

Reverberates an input signal with a "colored" frequency response.

Syntax		~

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

Initialization		~

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

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

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

Performance		~

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

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

Examples		~

Here is an example of the comb opcode. It uses the files comb.orc and
comb.sco.

Example 1. Example of the comb opcode.

 /* comb.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Initialize the audio mixer.
 gamix init 0

 ; Instrument #1.
 instr 1
; Generate a source signal.
a1 oscili 30000, cpspch(p4), 1
; Output the direct sound.
out a1 

; Add the source signal to the audio mixer.
gamix = gamix + a1
 endin

 ; Instrument #99 (highest instr number executed last)
 instr 99
krvt = 1.5
ilpt = 0.1

; Comb-filter the mixed signal.
a99 comb gamix, krvt, ilpt
; Output the result.
out a99

; Empty the mixer for the next pass.
gamix = 0
 endin
 /* comb.orc */

 /* comb.sco */
 ; Table #1, a sine wave.
 f 1 0 128 10 1

 ; p4 = frequency (in a pitch-class)
 ; Play Instrument #1 for a tenth of a second, p4=7.00
 i 1 0 0.1 7.00
 ; Play Instrument #1 for a tenth of a second, p4=7.02
 i 1 1 0.1 7.02
 ; Play Instrument #1 for a tenth of a second, p4=7.04
 i 1 2 0.1 7.04
 ; Play Instrument #1 for a tenth of a second, p4=7.06
 i 1 3 0.1 7.06

 ; Make sure the comb-filter remains active.
 i 99 0 5
 e
 /* comb.sco */

See Also		~

|alpass| alpass, |reverb| reverb, |valpass| valpass, |vcomb| vcomb

Credits		~

Author: William "Pete" Moss (vcomb and valpass) 
University of Texas at Austin                   
Austin, Texas USA                               
January 2002                                    

------------------------------------------------------------------------------
*control*
control	~

control --  Configurable slider controls for realtime user input.

Description		~

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

Syntax		~

kr control knum

Performance		~

knum -- number of the slider to be read.

Calling control will create a new slider on the screen. There is no
theoretical limit to the number of sliders. Windows and TCL/TK use only
integers for slider values, so the values may need rescaling. GUIs usually
pass values at a fairly slow rate, so it may be advisable to pass the output
of control through port.

Examples		~

See the |setctrl| setctrl opcode for an example.

See Also		~

|setctrl| setctrl

Credits		~

Author: John ffitch                
University of Bath, Codemist. Ltd. 
Bath, UK                           
May, 2000                          

New in Csound version 4.06

------------------------------------------------------------------------------
*convle*
convle	~

convle --  Same as the convolve opcode.

Description		~

Same as the |convolve| convolve opcode.

Syntax		~

ar1 [, ar2] [, ar3] [, ar4] convle ain, ifilcod [, ichannel]

------------------------------------------------------------------------------
*convolve*
convolve	~

convolve --  Convolves a signal and an impulse response.

Description		~

Output is the convolution of signal ain and the impulse response contained in
ifilcod. If more than one output signal is supplied, each will be convolved
with the same impulse response. Note that it is considerably more efficient
to use one instance of the operator when processing a mono input to create
stereo, or quad, outputs.

Note: this opcode can also be written as |convle| convle.

Syntax		~

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

Initialization		~

ifilcod -- integer or character-string denoting an impulse response data
file. An integer denotes the suffix of a file convolve.m; a character string
(in double quotes) gives a filename, optionally a full pathname. If not a
fullpath, the file is sought first in the current directory, then in the one
given by the environment variable SADIR (if defined). The data file contains
the Fourier transform of an impulse response. Memory usage depends on the
size of the data file, which is read and held entirely in memory during
computation, but which is shared by multiple calls.

ichannel (optional) -- which channel to use from the impulse response data
file.

Performance		~

ain -- input audio signal.

convolve implements Fast Convolution. The output of this operator is delayed
with respect to the input. The following formulas should be used to calculate
the delay:

For (1/kr) <= IRdur:
        Delay = ceil(IRdur * kr) / kr
For (1/kr)  IRdur:
        Delay = IRdur * ceil(1/(kr*IRdur))
Where:
        kr  = Csound control rate
        IRdur = duration, in seconds, of impulse response
        ceil(n) = smallest integer not smaller than n

One should be careful to also take into account the initial delay, if any, of
the impulse response. For example, if an impulse response is created from a
recording, the soundfile may not have the initial delay included. Thus, one
should either ensure that the soundfile has the correct amount of zero
padding at the start, or, preferably, compensate for this delay in the
orchestra. (the latter method is more efficient). To compensate for the delay
in the orchestra, subtract the initial delay from the result calculated using
the above formula(s), when calculating the required delay to introduce into
the 'dry' audio path.

For typical applications, such as reverb, the delay will be in the order of
0.5 to 1.5 seconds, or even longer. This renders the current implementation
unsuitable for real time applications. It could conceivably be used for real
time filtering however, if the number of taps is small enough.

The author intends to create a higher-level operator at some stage, that
would mix the wet & dry signals, using the correct amount of delay
automatically.

Examples		~

Create frequency domain impulse response file using the |cvanal| cvanal
utility:

 csound -Ucvanal l1_44.wav l1_44.cv

Determine duration of impulse response. For high accuracy, determine the
number of sample frames in the impulse response soundfile, and then compute
the duration with:

duration = (sample frames)/(sample rate of soundfile)

This is due to the fact that the |sndinfo| sndinfo utility only reports the
duration to the nearest 10ms. If you have a utility that reports the duration
to the required accuracy, then you can simply use the reported value
directly.

 sndinfo l1_44.wav

length = 60822 samples, sample rate = 44100
Duration = 60822/44100 = 1.379s.

Determine initial delay, if any, of impulse response. If the impulse response
has not had the initial delay removed, then you can skip this step. If it has
been removed, then the only way you will know the initial delay is if the
information has been provided separately. For this example, let's assume that
the initial delay is 60ms. (0.06s)

Determine the required delay to apply to the dry signal, to align it with the
convolved signal:

  If kr = 441:
        1/kr = 0.0023, which is <= IRdur (1.379s), so:
        Delay1  = ceil(IRdur * kr) / kr
                = ceil(608.14) / 441
                = 609/441
                = 1.38s

  Accounting for the initial delay:
        Delay2  = 0.06s
  Total delay   = delay1 - delay2
                = 1.38 - 0.06
                = 1.32s

Create .orc file, e.g.:

; Simple demonstration of CONVOLVE operator, to apply reverb.
      sr = 44100
      kr = 441
      ksmps = 100
      nchnls = 2
      instr   1
 imix = 0.22 ; Wet/dry mix. Vary as desired.
          ; NB: 'Small' reverbs often require a much higher
          ; percentage of wet signal to sound interesting. 'Large'
          ; reverbs seem require less. Experiment! The wet/dry mix is
          ; very important - a small change can make a large difference.
 ivol = 0.9  ; Overall volume level of reverb. May need to adjust
          ; when wet/dry mix is changed, to avoid clipping.
 idel = 1.32 ; Required delay to align dry audio with output of convolve.
          ; This can be automatically calculated within the orc file,
          ; if desired.
 adry            soundin "anechoic.wav"      ; input (dry) audio
 awet1,awet2     convolve adry,"l1_44.cv"    ; stereo convolved (wet) audio
 adrydel         delay   (1-imix)*adry,idel  ; Delay dry signal, to align it with
                                        ; convolved signal. Apply level
                                        ; adjustment here too.
              outs    ivol*(adrydel+imix*awet1),ivol*(adrydel+imix*awet2)
                                        ; Mix wet & dry signals, and output
      endin

Credits		~

Author: Greg Sullivan 
1996                  

------------------------------------------------------------------------------
*cos*
cos	~

cos --  Performs a cosine function.

Description		~

Returns the cosine of x (x in radians).

Syntax		~

cos(x) (no rate restriction)

Examples		~

Here is an example of the cos opcode. It uses the files cos.orc and cos.sco.

Example 1. Example of the cos opcode.

 /* cos.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
irad = 25
i1 = cos(irad)

print i1
 endin
 /* cos.orc */

 /* cos.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* cos.sco */

Its output should include lines like this:

 instr 1:  i1 = 0.991

See Also		~

|cosh| cosh, |cosinv| cosinv, |sin| sin, |sinh| sinh, |sininv| sininv, |tan|
tan, |tanh| tanh, |taninv| taninv

------------------------------------------------------------------------------
*cosh*
cosh	~

cosh --  Performs a hyperbolic cosine function.

Description		~

Returns the hyperbolic cosine of x (x in radians).

Syntax		~

cosh(x) (no rate restriction)

Examples		~

Here is an example of the cosh opcode. It uses the files cosh.orc and
cosh.sco.

Example 1. Example of the cosh opcode.

 /* cosh.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
irad = 1
i1 = cosh(irad)

print i1
 endin
 /* cosh.orc */

 /* cosh.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* cosh.sco */

Its output should include lines like this:

 instr 1:  i1 = 1.543

See Also		~

|cos| cos, |cosinv| cosinv, |sin| sin, |sinh| sinh, |sininv| sininv, |tan|
tan, |tanh| tanh, |taninv| taninv

------------------------------------------------------------------------------
*cosinv*
cosinv	~

cosinv --  Performs a arccosine function.

Description		~

Returns the arccosine of x (x in radians).

Syntax		~

cosinv(x) (no rate restriction)

Examples		~

Here is an example of the cosinv opcode. It uses the files cosinv.orc and
cosinv.sco.

Example 1. Example of the cosinv opcode.

 /* cosinv.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
irad = 0.5
i1 = cosinv(irad)

print i1
 endin
 /* cosinv.orc */

 /* cosinv.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* cosinv.sco */

Its output should include lines like this:

 instr 1:  i1 = 1.047

See Also		~

|cos| cos, |cosh| cosh, |sin| sin, |sinh| sinh, |sininv| sininv, |tan| tan,
|tanh| tanh, |taninv| taninv

------------------------------------------------------------------------------
*cps2pch*
cps2pch	~

cps2pch --  Converts a pitch-class value into cycles-per-second for equal
divisions of the octave.

Description		~

Converts a pitch-class value into cycles-per-second (Hz) for equal divisions
of the octave.

Syntax		~

icps cps2pch ipch, iequal

Initialization		~

ipch -- Input number of the form 8ve.pc, indicating an 'octave' and which
note in the octave.

iequal -- if positive, the number of equal intervals into which the 'octave'
is divided. Must be less than or equal to 100. If negative, is the number of
a table of frequency multipliers.

     Note                                                                     
      1. The following are essentially the same                               
         ia  =  cpspch(8.02)                                                  
         ib     cps2pch  8.02, 12                                             
         ic     cpsxpch  8.02, 12, 2, 1.02197503906                           
      2. These are opcodes not functions                                      
      3. Negative values of ipch are allowed.                                 

Examples		~

Here is an example of the cps2pch opcode. It uses the files cps2pch.orc and
cps2pch.sco.

Example 1. Example of the cps2pch opcode.

 /* cps2pch.orc */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Use a normal twelve-tone scale.
ipch = 8.02
iequal = 12

icps cps2pch ipch, iequal

print icps
 endin
 /* cps2pch.orc */

 /* cps2pch.sco */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* cps2pch.sco */

Its output should include lines like this:

 instr 1:  icps = 293.666

Here is an example of the cps2pch opcode using a table of frequency
multipliers. It uses the files cps2pch_ftable.orc and cps2pch_ftable.sco.

Example 2. Example of the cps2pch opcode using a table of frequency
multipliers.

 /* cps2pch_ftable.orc */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
ipch = 8.02

; Use Table #1, a table of frequency multipliers.
icps cps2pch ipch, -1

print icps
 endin
 /* cps2pch_ftable.orc */

 /* cps2pch_ftable.sco */
 ; Table #1: a table of frequency multipliers.
 ; Creates a 10-note scale of unequal divisions.
 f 1 0 16 -2 1 1.1 1.2 1.3 1.4 1.6 1.7 1.8 1.9

 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* cps2pch_ftable.sco */

Its output should include lines like this:

 instr 1:  icps = 313.951

Here is an example of the cps2pch opcode using a 19ET scale. It uses the
files cps2pch_19et.orc and cps2pch_19et.sco.

Example 3. Example of the cps2pch opcode using a 19ET scale.

 /* cps2pch_19et.orc */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Use 19ET scale.
ipch = 8.02
iequal = 19

icps cps2pch ipch, iequal

print icps
 endin
 /* cps2pch_19et.orc */

 /* cps2pch_19et.sco */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* cps2pch_19et.sco */

Its output should include lines like this:

 instr 1:  icps = 281.429

See Also		~

|cpspch| cpspch, |cpsxpch| cpsxpch

Credits		~

Author: John ffitch              
University of Bath/Codemist Ltd. 
Bath, UK                         
1997                             

Author: Gabriel Maldonado 
Italy                     
1998                      

New in Csound version 3.492

------------------------------------------------------------------------------
*cpsmidi*
cpsmidi	~

cpsmidi --  Get the note number of the current MIDI event, expressed in
cycles-per-second.

Description		~

Get the note number of the current MIDI event, expressed in
cycles-per-second.

Syntax		~

icps cpsmidi

Performance		~

Get the note number of the current MIDI event, expressed in cycles-per-second
units, for local processing.

Examples		~

Here is an example of the cpsmidi opcode. It uses the files cpsmidi.orc and
cpsmidi.sco.

Example 1. Example of the cpsmidi opcode.

 /* cpsmidi.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
i1 cpsmidi

print i1
 endin
 /* cpsmidi.orc */

 /* cpsmidi.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for 12 seconds.
 i 1 0 12
 e
 /* cpsmidi.sco */

See Also		~

|aftouch| aftouch, |ampmidi| ampmidi, |cpsmidib| cpsmidib, |cpstmid| cpstmid,
|midictrl| midictrl, |notnum| notnum, |octmidi| octmidi, |octmidib| octmidib,
|pchbend| pchbend, |pchmidi| pchmidi, |pchmidib| pchmidib, |veloc| veloc

Credits		~

Author: Barry L. Vercoe - Mike Berry 
MIT - Mills                          
May 1997                             

------------------------------------------------------------------------------
*cpsmidib*
cpsmidib	~

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.

Description		~

Get the note number of the current MIDI event and modify it by the current
pitch-bend value, express it in cycles-per-second.

Syntax		~

icps cpsmidib [irange]

kcps cpsmidib [irange]

Initialization		~

irange (optional) -- the pitch bend range in semitones.

Performance		~

Get the note number of the current MIDI event, modify it by the current
pitch-bend value, and express the result in cycles-per-second units.
Available as an i-time value or as a continuous k-rate value.

Examples		~

Here is an example of the cpsmidib opcode. It uses the files cpsmidib.orc and
cpsmidib.sco.

Example 1. Example of the cpsmidib opcode.

 /* cpsmidib.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
i1 cpsmidib

print i1
 endin
 /* cpsmidib.orc */

 /* cpsmidib.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for 12 seconds.
 i 1 0 12
 e
 /* cpsmidib.sco */

See Also		~

|aftouch| aftouch, |ampmidi| ampmidi, |cpsmidi| cpsmidi, |midictrl| midictrl,
|notnum| notnum, |octmidi| octmidi, |octmidib| octmidib, |pchbend| pchbend,
|pchmidi| pchmidi, |pchmidib| pchmidib, |veloc| veloc

Credits		~

Author: Barry L. Vercoe - Mike Berry 
MIT - Mills                          
May 1997                             

------------------------------------------------------------------------------
*cpsoct*
cpsoct	~

cpsoct --  Converts an octave-point-decimal value to cycles-per-second.

Description		~

Converts an octave-point-decimal value to cycles-per-second.

Syntax		~

cpsoct (oct) (no rate restriction)

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

Performance		~

These are really value converters with a special function of manipulating
pitch data.

Data concerning pitch and frequency can exist in any of the following forms:

Table 1. Pitch and Frequency Values

 Name                               Abbreviation  
 octave point pitch-class (8ve.pc)  pch           
 octave point decimal               oct           
 cycles per second                  cps           

The first two forms consist of a whole number, representing octave
registration, followed by a specially interpreted fractional part. For pch,
the fraction is read as two decimal digits representing the 12 equal-tempered
pitch classes from .00 for C to.11 for B. For oct, the fraction is
interpreted as a true decimal fractional part of an octave. The two
fractional forms are thus related by the factor 100/12. In both forms, the
fraction is preceded by a whole number octave index such that 8.00 represents
Middle C, 9.00 the C above, etc. Thus A440 can be represented alternatively
by 440 (cps),8.09 (pch), or 8.75 (oct). Microtonal divisions of the pch
semitone can be encoded by using more than two decimal places.

The mnemonics of the pitch conversion units are derived from morphemes of the
forms involved, the second morpheme describing the source and the first
morpheme the object (result). Thus cpspch(8.09) will convert the pitch
argument 8.09 to its cps (or Hertz) equivalent, giving the value of 440.
Since the argument is constant over the duration of the note, this conversion
will take place at i-time, before any samples for the current note are
produced.

By contrast, the conversion cpsoct(8.75 + k1) which gives the value of A440
transposed by the octave interval k1. The calculation will be repeated every
k-period since that is the rate at which k1 varies.

  Note                                                                        
  The conversion from pch or oct into cps is not a linear operation but       
  involves an exponential process that could be time-consuming when executed  
  repeatedly. Csound now uses a built-in table lookup to do this efficiently, 
  even at audio rates.                                                        

Examples		~

Here is an example of the cpsoct opcode. It uses the files cpsoct.orc and
cpsoct.sco.

Example 1. Example of the cpsoct opcode.

 /* cpsoct.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Convert an octave-point-decimal value into a
; cycles-per-second value.
ioct = 8.75
icps = cpsoct(ioct)

print icps
 endin
 /* cpsoct.orc */

 /* cpsoct.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* cpsoct.sco */

Its output should include lines like this:

 instr 1:  icps = 440.000

See Also		~

|cpspch| cpspch, |octcps| octcps, |octpch| octpch, |pchoct| pchoct

------------------------------------------------------------------------------
*cpspch*
cpspch	~

cpspch --  Converts a pitch-class value to cycles-per-second.

Description		~

Converts a pitch-class value to cycles-per-second.

Syntax		~

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

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

Performance		~

These are really value converters with a special function of manipulating
pitch data.

Data concerning pitch and frequency can exist in any of the following forms:

Table 1. Pitch and Frequency Values

 Name                               Abbreviation  
 octave point pitch-class (8ve.pc)  pch           
 octave point decimal               oct           
 cycles per second                  cps           

The first two forms consist of a whole number, representing octave
registration, followed by a specially interpreted fractional part. For pch,
the fraction is read as two decimal digits representing the 12 equal-tempered
pitch classes from .00 for C to.11 for B. For oct, the fraction is
interpreted as a true decimal fractional part of an octave. The two
fractional forms are thus related by the factor 100/12. In both forms, the
fraction is preceded by a whole number octave index such that 8.00 represents
Middle C, 9.00 the C above, etc. Thus A440 can be represented alternatively
by 440 (cps),8.09 (pch), or 8.75 (oct). Microtonal divisions of the pch
semitone can be encoded by using more than two decimal places.

The mnemonics of the pitch conversion units are derived from morphemes of the
forms involved, the second morpheme describing the source and the first
morpheme the object (result). Thus cpspch(8.09) will convert the pitch
argument 8.09 to its cps (or Hertz) equivalent, giving the value of 440.
Since the argument is constant over the duration of the note, this conversion
will take place at i-time, before any samples for the current note are
produced.

By contrast, the conversion cpsoct(8.75 + k1) which gives the value of A440
transposed by the octave interval k1. The calculation will be repeated every
k-period since that is the rate at which k1 varies.

  Note                                                                        
  The conversion from pch or oct into cps is not a linear operation but       
  involves an exponential process that could be time-consuming when executed  
  repeatedly. Csound now uses a built-in table lookup to do this efficiently, 
  even at audio rates.                                                        

Examples		~

Here is an example of the cpspch opcode. It uses the files cpspch.orc and
cpspch.sco.

Example 1. Example of the cpspch opcode.

 /* cpspch.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Convert a pitch-class value into a
; cycles-per-second value.
ipch = 8.09
icps = cpspch(ipch)

print icps
 endin
 /* cpspch.orc */

 /* cpspch.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* cpspch.sco */

Its output should include lines like this:

 instr 1:  icps = 440.000

See Also		~

|cps2pch| cps2pch, |cpsoct| cpsoct, |cpsxpch| cpsxpch, |octcps| octcps,
|octpch| octpch, |pchoct| pchoct

------------------------------------------------------------------------------
*cpstmid*
cpstmid	~

cpstmid --  Get a MIDI note number (allows customized micro-tuning scales).

Description		~

This unit is similar to |cpsmidi| cpsmidi, but allows fully customized
micro-tuning scales.

Syntax		~

icps cpstmid ifn

Initialization		~

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

Performance		~

Init-rate only

cpsmid requires five parameters, the first, ifn, is the function table number
of the tuning ratios, and the other parameters must be stored in the function
table itself. The function table ifn should be generated by |gen02| GEN02,
with normalization inhibited. The first four values stored in this function
are:

 1. numgrades -- the number of grades of the micro-tuning scale

 2. interval -- the frequency range covered before repeating the grade
    ratios, for example 2 for one octave, 1.5 for a fifth etc.

 3. basefreq -- the base frequency of the scale in Hz

 4. basekeymidi -- the MIDI note number to which basefreq is assigned
    unmodified

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

  ;          numgrades interval  basefreq basekeymidi tuning ratios (equal temp)   
  f1 0 64 -2   12       2        261        60         1  1.059463094359  1.122462048309  1.189207115003 ..etc...  

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

  ;           numgrades interval  basefreq basekeymidi tuning-ratios (equal temp)   
  f1 0 64 -2   24        1.5      440        48         1   1.01  1.02  1.03   ..etc...  

Examples		~

Here is an example of the cpstmid opcode. It uses the files cpstmid.orc and
cpstmid.sco.

Example 1. Example of the cpstmid opcode.

 /* cpstmid.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Table #1, a normal 12-tone equal temperament scale.
 ; numgrades = 12 (twelve tones)
 ; interval = 2 (one octave)
 ; basefreq = 261.659 (Middle C)
 ; basekeymidi = 60 (Middle C)
 gitemp ftgen 1, 0, 64, -2, 12, 2, 261.659, 60, 1.00, \
           1.059, 1.122, 1.189, 1.260, 1.335, 1.414, \
           1.498, 1.588, 1.682, 1.782, 1.888, 2.000

 ; Instrument #1.
 instr 1
; Use Table #1.
ifn = 1
i1 cpstmid ifn

print i1
 endin
 /* cpstmid.orc */

 /* cpstmid.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for 12 seconds.
 i 1 0 12
 e
 /* cpstmid.sco */

See Also		~

|cpsmidi| cpsmidi, |gen02| GEN02

Credits		~

Author: Gabriel Maldonado 
Italy                     
1998                      

New in Csound version 3.492

------------------------------------------------------------------------------
*cpstun*
cpstun	~

cpstun --  Returns micro-tuning values at k-rate.

Description		~

Returns micro-tuning values at k-rate.

Syntax		~

kcps cpstun ktrig, kindex, kfn

Performance		~

kcps -- Return value in cycles per second.

ktrig -- A trigger signal used to trigger the evaluation.

kindex -- An integer number denoting an index of scale.

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

These opcodes are similar to cpstmid, but work without necessity of MIDI.

cpstun works at k-rate. It allows fully customized micro-tuning scales. It
requires a function table number containing the tuning ratios, and some other
parameters stored in the function table itself.

kindex arguments should be filled with integer numbers expressing the grade
of given scale to be converted in cps. In cpstun, a new value is evaluated
only when ktrig contains a non-zero value. The function table kfn should be
generated by |gen02| GEN02 and the first four values stored in this function
are parameters that express:

  * numgrades -- The number of grades of the micro-tuning scale.

  * interval -- The frequency range covered before repeating the grade
    ratios, for example 2 for one octave, 1.5 for a fifth etcetera.

  * basefreq -- The base frequency of the scale in cycles per second.

  * basekey -- The integer index of the scale to which to assign basefreq
    unmodified.

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

 ;           numgrades    basefreq     tuning-ratios (eq.temp) .......
 ;                  interval    basekey
 f1 0 64 -2  12     2     261   60     1   1.059463 1.12246 1.18920 ..etc...

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

                numgrades       basefreq      tuning-ratios .......
                        interval       basekey
 f1 0 64 -2         24      1.5     440    48     1   1.01  1.02  1.03   ..etc...

Examples		~

Here is an example of the cpstun opcode. It uses the files cpstun.orc and
cpstun.sco.

Example 1. Example of the cpstun opcode.

 /* cpstun.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Table #1, a normal 12-tone equal temperament scale.
 ; numgrades = 12 (twelve tones)
 ; interval = 2 (one octave)
 ; basefreq = 261.659 (Middle C)
 ; basekeymidi = 60 (Middle C)
 gitemp ftgen 1, 0, 64, -2, 12, 2, 261.659, 60, 1.00, \
           1.059, 1.122, 1.189, 1.260, 1.335, 1.414, \
           1.498, 1.588, 1.682, 1.782, 1.888, 2.000

 ; Instrument #1.
 instr 1
; Set the trigger.
ktrig init 1

; Use Table #1.
kfn init 1

; If the base key (note #60) is C, then 9 notes
; above it (note #60 + 9 = note #69) should be A.
kindex init 69

k1 cpstun ktrig, kindex, kfn

printk2 k1
 endin
 /* cpstun.orc */

 /* cpstun.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* cpstun.sco */

Its output should include lines like this:

i1   440.11044

See Also		~

|cpstmid| cpstmid, |cpstuni| cpstuni, |gen02| GEN02

------------------------------------------------------------------------------
*cpstuni*
cpstuni	~

cpstuni --  Returns micro-tuning values at init-rate.

Description		~

Returns micro-tuning values at init-rate.

Syntax		~

icps cpstuni index, ifn

Initialization		~

icps -- Return value in cycles per second.

index -- An integer number denoting an index of scale.

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

Performance		~

These opcodes are similar to |cpstmid| cpstmid, but work without necessity of
MIDI.

cpstuni works at init-rate. It allows fully customized micro-tuning scales.
It requires a function table number containing the tuning ratios, and some
other parameters stored in the function table itself.

The index argument should be filled with integer numbers expressing the grade
of given scale to be converted in cps. The function table ifn should be
generated by |gen02| GEN02 and the first four values stored in this function
are parameters that express:

  * numgrades -- The number of grades of the micro-tuning scale.

  * interval -- The frequency range covered before repeating the grade
    ratios, for example 2 for one octave, 1.5 for a fifth etcetera.

  * basefreq -- The base frequency of the scale in cycles per second.

  * basekey -- The integer index of the scale to which to assign basefreq
    unmodified.

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

 ;           numgrades    basefreq     tuning-ratios (eq.temp) .......
 ;                  interval    basekey
 f1 0 64 -2  12     2     261   60     1   1.059463 1.12246 1.18920 ..etc...

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

                numgrades       basefreq      tuning-ratios .......
                        interval       basekey
 f1 0 64 -2         24      1.5     440    48     1   1.01  1.02  1.03   ..etc...

Examples		~

Here is an example of the cpstuni opcode. It uses the files cpstuni.orc and
cpstuni.sco.

Example 1. Example of the cpstuni opcode.

 /* cpstuni.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Table #1, a normal 12-tone equal temperament scale.
 ; numgrades = 12 (twelve tones)
 ; interval = 2 (one octave)
 ; basefreq = 261.659 (Middle C)
 ; basekeymidi = 60 (Middle C)
 gitemp ftgen 1, 0, 64, -2, 12, 2, 261.659, 60, 1.00, \
           1.059, 1.122, 1.189, 1.260, 1.335, 1.414, \
           1.498, 1.588, 1.682, 1.782, 1.888, 2.000

 ; Instrument #1.
 instr 1
; Use Table #1.
ifn = 1

; If the base key (note #60) is C, then 9 notes
; above it (note #60 + 9 = note #69) should be A.
index = 69

i1 cpstuni index, ifn

print i1
 endin
 /* cpstuni.orc */

 /* cpstuni.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* cpstuni.sco */

Its output should include lines like this:

 instr 1:  i1 = 440.110

See Also		~

|cpstmid| cpstmid, |cpstun| cpstun, |gen02| GEN02

------------------------------------------------------------------------------
*cpsxpch*
cpsxpch	~

cpsxpch --  Converts a pitch-class value into cycles-per-second (Hz) for
equal divisions of any interval.

Description		~

Converts a pitch-class value into cycles-per-second (Hz) for equal divisions
of any interval. There is a restriction of no more than 100 equal divisions.

Syntax		~

icps cpsxpch ipch, iequal, irepeat, ibase

Initialization		~

ipch -- Input number of the form 8ve.pc, indicating an 'octave' and which
note in the octave.

iequal -- if positive, the number of equal intervals into which the 'octave'
is divided. Must be less than or equal to 100. If negative, is the number of
a table of frequency multipliers.

irepeat -- Number indicating the interval which is the 'octave.' The integer
2 corresponds to octave divisions, 3 to a twelfth, 4 is two octaves, and so
on. This need not be an integer, but must be positive.

ibase -- The frequency which corresponds to pitch 0.0

  Note                                                                        
   1. The following are essentially the same                                  
      ia  =  cpspch(8.02)                                                     
      ib     cps2pch  8.02, 12                                                
      ic     cpsxpch  8.02, 12, 2, 1.02197503906                              
   2. These are opcodes not functions                                         
   3. Negative values of ipch are allowed, but not negative irepeat, iequal   
      or ibase.                                                               

Examples		~

Here is an example of the cpsxpch opcode. It uses the files cpsxpch.orc and
cpsxpch.sco.

Example 1. Example of the cpsxpch opcode.

 /* cpsxpch.orc */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Use a normal twelve-tone scale.
ipch = 8.02
iequal = 12
irepeat = 2
ibase = 1.02197503906

icps cpsxpch ipch, iequal, irepeat, ibase

print icps
 endin
 /* cpsxpch.orc */

 /* cpsxpch.sco */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* cpsxpch.sco */

Its output should include lines like this:

 instr 1:  icps = 293.666

Here is an example of the cpsxpch opcode using a 10.5 ET scale. It uses the
files cpsxpch_105et.orc and cpsxpch_105et.sco.

Example 2. Example of the cpsxpch opcode using a 10.5 ET scale.

 /* cpsxpch_105et.orc */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Use a 10.5ET scale.
ipch = 4.02
iequal = 21
irepeat = 4
ibase = 16.35160062496

icps cpsxpch ipch, iequal, irepeat, ibase

print icps
 endin
 /* cpsxpch_105et.orc */

 /* cpsxpch_105et.sco */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* cpsxpch_105et.sco */

Its output should include lines like this:

 instr 1:  icps = 4776.824

Here is an example of the cpsxpch opcode using a Pierce scale centered on
middle A. It uses the files cpsxpch_pierce.orc and cpsxpch_pierce.sco.

Example 3. Example of the cpsxpch opcode using a Pierce scale centered on
middle A.

 /* cpsxpch_pierce.orc */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Use a Pierce scale centered on middle A.
ipch = 2.02
iequal = 12
irepeat = 3
ibase = 261.62561

icps cpsxpch ipch, iequal, irepeat, ibase

print icps
 endin
 /* cpsxpch_pierce.orc */

 /* cpsxpch_pierce.sco */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* cpsxpch_pierce.sco */

Its output should include lines like this:

 instr 1:  icps = 2827.762

See Also		~

|cpspch| cpspch, |cps2pch| cps2pch

Credits		~

Author: John ffitch              
University of Bath/Codemist Ltd. 
Bath, UK                         
1997                             

Author: Gabriel Maldonado 
Italy                     
1998                      

New in Csound version 3.492

------------------------------------------------------------------------------
*cpuprc*
cpuprc	~

cpuprc --  Control allocation of cpu resources on a per-instrument basis, to
optimize realtime output.

Description		~

Control allocation of cpu resources on a per-instrument basis, to optimize
realtime output.

Syntax		~

cpuprc insnum, ipercent

Initialization		~

insnum -- instrument number

ipercent -- percent of cpu processing-time to assign. Can also be expressed
as a fractional value.

Performance		~

cpuprc sets the cpu processing-time percent usage of an instrument, in order
to avoid buffer underrun in realtime performances, enabling a sort of
polyphony theshold. The user must set ipercent value for each instrument to
be activated in realtime. Assuming that the total theoretical processing time
of the cpu of the computer is 100%, this percent value can only be defined
empirically, because there are too many factors that contribute to limiting
realtime polyphony in different computers.

For example, if ipercent is set to 5% for instrument 1, the maximum number of
voices that can be allocated in realtime, is 20 (5% * 20 = 100%). If the user
attempts to play a further note while the 20 previous notes are still
playing, Csound inhibits the allocation of that note and will display the
following warning message:

  can't allocate last note because it exceeds 100% of cpu time

In order to avoid audio buffer underruns, it is suggested to set the maximum
number of voices slightly lower than the real processing power of the
computer. Sometimes an instrument can require more processing time than
normal. If, for example, the instrument contains an oscillator which reads a
table that doesn't fit in cache memory, it will be slower than normal. In
addition, any program running concurrently in multitasking, can subtract
processing power to varying degrees.

At the start, all instruments are set to a default value of ipercent = 0.0%
(i.e. zero processing time or rather infinite cpu processing-speed). This
setting is OK for deferred-time sessions.

All instances of cpuprc must be defined in the header section, not in the
instrument body.

Examples		~

Here is an example of the cpuprc opcode. It uses the files cpuprc.orc and
cpuprc.sco.

Example 1. Example of the cpuprc opcode.

 /* cpuprc.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Limit Instrument #1 to 5% of the CPU processing time.
 cpuprc 1, 5
 ; Instrument #1
 instr 1
a1 oscil 10000, 440, 1
out a1
 endin
 /* cpuprc.orc */

 /* cpuprc.sco */
 /* Written by Kevin Conder */
 ; Just generate a nice, ordinary sine wave.
 f 1 0 32768 10 1

 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* cpuprc.sco */

See Also		~

|maxalloc| maxalloc, |prealloc| prealloc

Credits		~

Author: Gabriel Maldonado 
Italy                     
July, 1999                

New in Csound version 3.57

------------------------------------------------------------------------------
*cross2*
cross2	~

cross2 --  Cross synthesis using FFT's.

Description		~

This is an implementation of cross synthesis using FFT's.

Syntax		~

ar cross2 ain1, ain2, isize, ioverlap, iwin, kbias

Initialization		~

isize -- This is the size of the FFT to be performed. The larger the size the
better the frequency response but a sloppy time response.

ioverlap -- This is the overlap factor of the FFT's, must be a power of two.
The best settings are 2 and 4. A big overlap takes a long time to compile.

iwin -- This is the function table that contains the window to be used in the
analysis. One can use the |gen20| GEN20 routine to create this window.

Performance		~

ain1 -- The stimulus sound. Must have high frequencies for best results.

ain2 -- The modulating sound. Must have a moving frequency response (like
speech) for best results.

kbias -- The amount of cross synthesis. 1 is the normal, 0 is no cross
synthesis.

Examples		~

Here is an example of the cross2 opcode. It uses the files cross2.orc,
cross2.sco and beats.wav.

Example 1. Example of the cross2 opcode.

 /* cross2.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1 - Play an audio file.
 instr 1
; Use the "beats.wav" audio file.
aout soundin "beats.wav"
out aout
 endin

 ; Instrument #2 - Cross-synthesize!
 instr 2
; Use the "ahh" sound stored in Table #1.
ain1 loscil 30000, 1, 1, 1
; Use the "beats.wav" audio file.
ain2 soundin "beats.wav"

isize = 4096
ioverlap = 2
iwin = 2
kbias init 1

aout cross2 ain1, ain2, isize, ioverlap, iwin, kbias

out aout
 endin
 /* cross2.orc */

 /* cross2.sco */
 /* Written by Kevin Conder */
 ; Table #1: An audio file.
 f 1 0 128 1 "ahh.aiff" 0 4 0
 ; Table #2: A windowing function.
 f 2 0 2048 20 2

 ; Play Instrument #1 for 2 seconds.
 i 1 0 2
 ; Play Instrument #2 for 2 seconds.
 i 2 2 2
 e
 /* cross2.sco */

Credits		~

Author: Paris Smaragdis 
MIT, Cambridge          
1997                    

------------------------------------------------------------------------------
*crunch*
crunch	~

crunch --  Semi-physical model of a crunch sound.

Description		~

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

Syntax		~

ar crunch iamp, idettack [, inum] [, idamp] [, imaxshake]

Initialization		~

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

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

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

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

damping_amount = 0.998 + (idamp * 0.002)

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

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

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

Examples		~

Here is an example of the crunch opcode. It uses the files crunch.orc and
crunch.sco.

Example 1. Example of the crunch opcode.

 /* crunch.orc */
 ;orchestra ---------------

sr =           44100
kr =            4410
ksmps =              10
nchnls =               1

 instr 01                  ;an example of a crunch
 a1      crunch p4, 0.01
        out a1
        endin
 /* crunch.orc */

 /* crunch.sco */
 ;score -------------------

 i1 0 1 26000
 e
 /* crunch.sco */

See Also		~

|cabasa| cabasa, |sandpaper| sandpaper, |sekere| sekere, |stix| stix

Credits		~

Author: Perry Cook, part of the PhOLIES (Physically-Oriented Library of       
Imitated Environmental Sounds)                                                
Adapted by John ffitch                                                        
University of Bath, Codemist Ltd.                                             
Bath, UK                                                                      

New in Csound version 4.07

Added notes by Rasmus Ekman on May 2002.

------------------------------------------------------------------------------
*ctrl14*
ctrl14	~

ctrl14 --  Allows a floating-point 14-bit MIDI signal scaled with a minimum
and a maximum range.

Description		~

Allows a floating-point 14-bit MIDI signal scaled with a minimum and a
maximum range.

Syntax		~

idest ctrl14 ichan, ictlno1, ictlno2, imin, imax [, ifn]

kdest ctrl14 ichan, ictlno1, ictlno2, kmin, kmax [, ifn]

Initialization		~

idest -- output signal

ichan -- MIDI channel number (1-16)

ictln1o -- most-significant byte controller number (0-127)

ictlno2 -- least-significant byte controller number (0-127)

imin -- user-defined minimum floating-point value of output

imax -- user-defined maximum floating-point value of output

ifn (optional) -- table to be read when indexing is required. Table must be
normalized. Output is scaled according to imax and imin val.

Performance		~

kdest -- output signal

kmin -- user-defined minimum floating-point value of output

kmax -- user-defined maximum floating-point value of output

ctrl14 (i- and k-rate 14 bit MIDI control) allows a floating-point 14-bit
MIDI signal scaled with a minimum and a maximum range. The minimum and
maximum values can be varied at k-rate. It can use optional interpolated
table indexing. It requires two MIDI controllers as input.

ctrl14 differs from |midic14| midic14 becase it can be included in
score-oriented instruments without Csound crashes. It needs the additional
parameter ichan containing the MIDI channel of the controller. MIDI channel
is the same for all the controllers used in a single ctrl14 opcode.

See Also		~

|ctrl7| ctrl7, |ctrl21| ctrl21, |initc7| initc7, |initc14| initc14, |initc21|
initc21, |midic7| midic7, |midic14| midic14, |midic21| midic21

Credits		~

Author: Gabriel Maldonado 
Italy                     

New in Csound version 3.47

Thanks goes to Rasmus Ekman for pointing out the correct MIDI channel and
controller number ranges.

------------------------------------------------------------------------------
*ctrl21*
ctrl21	~

ctrl21 --  Allows a floating-point 21-bit MIDI signal scaled with a minimum
and a maximum range.

Description		~

Allows a floating-point 21-bit MIDI signal scaled with a minimum and a
maximum range.

Syntax		~

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

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

Initialization		~

idest -- output signal

ichan -- MIDI channel number (1-16)

ictlno -- MIDI controller number (0-127)

ictln1o -- most-significant byte controller number (0-127)

ictlno2 -- mid-significant byte controller number (0-127)

ictlno3 -- least-significant byte controller number (0-127)

imin -- user-defined minimum floating-point value of output

imax -- user-defined maximum floating-point value of output

ifn (optional) -- table to be read when indexing is required. Table must be
normalized. Output is scaled according to imax and imin val.

Performance		~

kdest -- output signal

kmin -- user-defined minimum floating-point value of output

kmax -- user-defined maximum floating-point value of output

ctrl21 (i- and k-rate 21 bit MIDI control) allows a floating-point 21-bit
MIDI signal scaled with a minimum and a maximum range. Minimum and maximum
values can be varied at k-rate. It can use optional interpolated table
indexing. It requires three MIDI controllers as input.

ctrl21 differs from |midic21| midic21 because it can be included in score
oriented instruments without Csound crashes. It needs the additional
parameter ichan containing the MIDI channel of the controller. MIDI channel
is the same for all the controllers used in a single ctrl21 opcode.

See Also		~

|ctrl7| ctrl7, |ctrl14| ctrl14, |initc7| initc7, |initc14| initc14, |initc21|
initc21, |midic7| midic7, |midic14| midic14, |midic21| midic21

Credits		~

Author: Gabriel Maldonado 
Italy                     

New in Csound version 3.47

Thanks goes to Rasmus Ekman for pointing out the correct MIDI channel and
controller number ranges.

------------------------------------------------------------------------------
*ctrl7*
ctrl7	~

ctrl7 --  Allows a floating-point 7-bit MIDI signal scaled with a minimum and
a maximum range.

Description		~

Allows a floating-point 7-bit MIDI signal scaled with a minimum and a maximum
range.

Syntax		~

idest ctrl7 ichan, ictlno, imin, imax [, ifn]

kdest ctrl7 ichan, ictlno, kmin, kmax [, ifn]

Initialization		~

idest -- output signal

ichan -- MIDI channel (1-16)

ictlno -- MIDI controller number (0-127)

imin -- user-defined minimum floating-point value of output

imax -- user-defined maximum floating-point value of output

ifn (optional) -- table to be read when indexing is required. Table must be
normalized. Output is scaled according to imax and imin val.

Performance		~

kdest -- output signal

kmin -- user-defined minimum floating-point value of output

kmax -- user-defined maximum floating-point value of output

ctrl7 (i- and k-rate 7 bit MIDI control) allows a floating-point 7-bit MIDI
signal scaled with a minimum and a maximum range. It also allows optional
non-interpolated table indexing. Minimum and maximum values can be varied at
k-rate.

ctrl7 differs from |midic7| midic7 because it can be included in
score-oriented instruments without Csound crashes. It also needs the
additional parameter ichan containing the MIDI channel of the controller.

See Also		~

|ctrl14| ctrl14, |ctrl21| ctrl21, |initc7| initc7, |initc14| initc14,
|initc21| initc21, |midic7| midic7, |midic14| midic14, |midic21| midic21

Credits		~

Author: Gabriel Maldonado 
Italy                     

New in Csound version 3.47

Thanks goes to Rasmus Ekman for pointing out the correct MIDI channel and
controller number ranges.

------------------------------------------------------------------------------
*ctrlinit*
ctrlinit	~

ctrlinit --  Sets the initial values for a set of MIDI controllers.

Description		~

Sets the initial values for a set of MIDI controllers.

Syntax		~

ctrlinit ichnl, ictlno1, ival1 [, ictlno2] [, ival2] [, ictlno3] [, ival3]
[,...ival32]

Initialization		~

ichnl -- MIDI channel number (1-16)

ictlno1, ictlno1, etc. -- MIDI controller numbers (0-127)

ival1, ival2, etc. -- initial value for corresponding MIDI controller number

Performance		~

Sets the initial values for a set of MIDI controllers.

See Also		~

|massign| massign

Credits		~

Author: Barry L. Vercoe - Mike Berry 
MIT, Cambridge, Mass.                

New in Csound version 3.47

Thanks goes to Rasmus Ekman for pointing out the correct MIDI channel and
controller number ranges.

------------------------------------------------------------------------------
*cuserrnd*
cuserrnd	~

cuserrnd --  Continuous USER-defined-distribution RaNDom generator.

Description		~

Continuous USER-defined-distribution RaNDom generator.

Syntax		~

aout cuserrnd kmin, kmax, ktableNum

iout cuserrnd imin, imax, itableNum

kout cuserrnd kmin, kmax, ktableNum

Initialization		~

imin -- minimum range limit

imax -- maximum range limit

itableNum -- number of table containing the random-distribution function.
Such table is generated by the user. See |gen40| GEN40, |gen41| GEN41, and
|gen42| GEN42. The table length does not need to be a power of 2

Performance		~

ktableNum -- number of table containing the random-distribution function.
Such table is generated by the user. See |gen40| GEN40, |gen41| GEN41, and
|gen42| GEN42. The table length does not need to be a power of 2

kmin -- minimum range limit

kmax -- maximum range limit

cuserrnd (continuous user-defined-distribution random generator) generates
random values according to a continuous random distribution created by the
user. In this case the shape of the distribution histogram can be drawn or
generated by any GEN routine. The table containing the shape of such
histogram must then be translated to a distribution function by means of
GEN40 (see |gen40| GEN40 for more details). Then such function must be
assigned to the XtableNum argument of cuserrnd. The output range can then be
rescaled according to the Xmin and Xmax arguments. cuserrnd linearly
interpolates between table elements, so it is not recommended for discrete
distributions (|gen41| GEN41 and |gen42| 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.

See Also		~

|duserrnd| duserrnd, |urd| urd

Credits		~

Author: Gabriel Maldonado

New in Version 4.16

------------------------------------------------------------------------------
*dam*
dam	~

dam --  A dynamic compressor/expander.

Description		~

This opcode dynamically modifies a gain value applied to the input sound ain
by comparing its power level to a given threshold level. The signal will be
compressed/expanded with different factors regarding that it is over or under
the threshold.

Syntax		~

ar dam asig, kthreshold, icomp1, icomp2, irtime, iftime

Initialization		~

icomp1 -- compression ratio for upper zone.

icomp2 -- compression ratio for lower zone

irtime -- gain rise time in seconds. Time over which the gain factor is
allowed to raise of one unit.

iftime -- gain fall time in seconds. Time over which the gain factor is
allowed to decrease of one unit.

Performance		~

asig -- input signal to be modified

kthreshold -- level of input signal which acts as the threshold. Can be
changed at k-time (e.g. for ducking)

Note on the compression factors: A compression ratio of one leaves the sound
unchanged. Setting the ratio to a value smaller than one will compress the
signal (reduce its volume) while setting the ratio to a value greater than
one will expand the signal (augment its volume).

Examples		~

Because the results of the dam opcode can be subtle, I recommend looking at
them in a graphical audio editor program like audacity. audacity is available
for Linux, Windows, and the MacOS and may be downloaded from
http://audacity.sourceforge.net.

Here is an example of the dam opcode. It uses the files dam.orc, dam.sco, and
beats.wav.

Example 1. An example of the dam opcode compressing an audio signal.

 /* dam.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1, uncompressed signal.
 instr 1
; Use the "beats.wav" audio file.
asig soundin "beats.wav"

out asig
 endin

 ; Instrument #2, compressed signal.
 instr 2
; Use the "beats.wav" audio file.
asig soundin "beats.wav"

; Compress the audio signal.
kthreshold init 25000
icomp1 = 0.5
icomp2 = 0.763
irtime = 0.1
iftime = 0.1
a1 dam asig, kthreshold, icomp1, icomp2, irtime, iftime

out a1
 endin
 /* dam.orc */

 /* dam.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for 2 seconds.
 i 1 0 2
 ; Play Instrument #2 for 2 seconds.
 i 2 2 2
 e
 /* dam.sco */

This example compresses the audio file "beats.wav". You should hear a drum
pattern repeat twice. The second time, the sound should be quieter
(compressed) than the first.

Here is another example of the dam opcode. It uses the files
dam_expanded.orc, dam_expanded.sco, and mary.wav.

Example 2. An example of the dam opcode expanding an audio signal.

 /* dam_expanded.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1, normal audio signal.
 instr 1
; Use the "mary.wav" audio file.
asig soundin "mary.wav"

out asig
 endin

 ; Instrument #2, expanded audio signal.
 instr 2
; Use the "mary.wav" audio file.
asig soundin "mary.wav"

; Expand the audio signal.
kthreshold init 7500
icomp1 = 2.25
icomp2 = 2.25
irtime = 0.1
iftime = 0.6
a1 dam asig, kthreshold, icomp1, icomp2, irtime, iftime

out a1
 endin
 /* dam_expanded.orc */

 /* dam_expanded.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1.
 i 1 0.0 3.5
 ; Play Instrument #2.
 i 2 3.5 3.5
 e
 /* dam_expanded.sco */

This example expands the audio file "mary.wav". You should hear a melody
repeat twice. The second time, the sound should be louder (expanded) than the
first.

Credits		~

Author: Marc Resibois 
Belgium               
1997                  

------------------------------------------------------------------------------
*db*
db	~

db --  Returns the amplitude equivalent for a given decibel amount.

Description		~

Returns the amplitude equivalent for a given decibel amount. This opcode is
the same as |ampdb| db.

Syntax		~

db(x)

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

Initialization		~

x -- a value expressed in decibels.

Performance		~

Returns the amplitude for a given decibel amount.

Examples		~

Here is an example of the db opcode. It uses the files db.orc and db.sco.

Example 1. Example of the db opcode.

 /* db.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Calculate the amplitude of 40 decibels.
idecibels = 40
iamp = db(idecibels)

print iamp
 endin
 /* db.orc */

 /* db.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* db.sco */

Its output should include lines like:

 instr 1:  iamp = 100.000

See Also		~

|ampdb| ampdb, |cent| cent, |octave| octave, |semitone| semitone

Credits		~

New in version 4.16

------------------------------------------------------------------------------
*dbamp*
dbamp	~

dbamp --  Returns the decibel equivalent of the raw amplitude x.

Description		~

Returns the decibel equivalent of the raw amplitude x.

Syntax		~

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

Examples		~

Here is an example of the dbamp opcode. It uses the files dbamp.orc and
dbamp.sco.

Example 1. Example of the dbamp opcode.

 /* dbamp.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
iamp = 30000
idb = dbamp(iamp)

print idb
 endin
 /* dbamp.orc */

 /* dbamp.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* dbamp.sco */

Its output should include lines like this:

 instr 1:  idb = 89.542

See Also		~

|ampdb| ampdb, |ampdbfs| ampdbfs, |dbfsamp| dbfsamp

------------------------------------------------------------------------------
*dbfsamp*
dbfsamp	~

dbfsamp --  Returns the decibel equivalent of the raw amplitude x, relative
to full scale amplitude.

Description		~

Returns the decibel equivalent of the raw amplitude x, relative to full scale
amplitude. Full scale is assumed to be 16 bit. New is Csound version 4.10.

Syntax		~

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

Examples		~

Here is an example of the dbfsamp opcode. It uses the files dbfsamp.orc and
dbfsamp.sco.

Example 1. Example of the dbfsamp opcode.

 /* dbfsamp.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
iamp = 30000
idb = dbfsamp(iamp)

print idb
 endin
 /* dbfsamp.orc */

 /* dbfsamp.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* dbfsamp.sco */

Its output should include lines like this:

 instr 1:  idb = -0.767

See Also		~

|ampdb| ampdb, |ampdbfs| ampdbfs, |dbamp| dbamp

------------------------------------------------------------------------------
*dcblock*
dcblock	~

dcblock --  A DC blocking filter.

Description		~

Implements the DC blocking filter

Y[i] = X[i] - X[i-1] + (igain * Y[i-1])

Based on work by Perry Cook.

Syntax		~

ar dcblock ain [, igain]

Initialization		~

igain -- the gain of the filter, which defaults to 0.99

Performance		~

ain -- audio signal input

Examples		~

Here is an example of the dcblock opcode. It uses the files dcblock.orc,
dcblock.sco, and beats.wav.

Example 1. Example of the dcblock opcode.

 /* dcblock.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1 -- normal audio signal.
 instr 1
asig soundin "beats.wav"
out asig
 endin

 ; Instrument #2 -- dcblock-ed audio signal.
 instr 2
asig soundin "beats.wav"

igain = 0.75
a1 dcblock asig, igain

out a1
 endin
 /* dcblock.orc */

 /* dcblock.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for 2 seconds.
 i 1 0 2
 ; Play Instrument #2 for 2 seconds.
 i 2 2 2
 e
 /* dcblock.sco */

Credits		~

Author: John ffitch               
University of Bath, Codemist Ltd. 
Bath, UK                          

New in Csound version 3.49

February 2003: Thanks to a note from Anders Andersson, corrected the formula.

------------------------------------------------------------------------------
*dconv*
dconv	~

dconv --  A direct convolution opcode.

Description		~

A direct convolution opcode.

Syntax		~

ar dconv asig, isize, ifn

Initialization		~

isize -- the size of the convolution buffer to use. if the buffer size is
smaller than the size of ifn, then only the first isize values will be used
from the table.

ifn -- table number of a stored function containing the impulse response for
convolution.

Performance		~

Rather than the analysis/resynthesis method of the convolve opcode, dconv
uses direct convolution to create the result. For small tables it can do this
quite efficiently, however larger table require much more time to run. dconv
does (isize * ksmps) multiplies on every k-cycle. Therefore, reverb and delay
effects are best done with other opcodes (unless the times are short).

dconv was designed to be used with time varying tables to facilitate new
realtime filtering capabilities.

Examples		~

Here is an example of the dconv opcode. It uses the files dconv.orc and
dconv.sco.

Example 1. Example of the dconv opcode.

 /* dconv.orc */
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1
 #define RANDI(A) #kout  randi   1, kfq, $A*.001+iseed, 1
      tablew  kout, $A, itable#
 instr 1
 itable  init    1
 iseed   init    .6
 isize   init    ftlen(itable)
 kfq     line    1, p3, 10
 $RANDI(0)
 $RANDI(1)
 $RANDI(2)
 $RANDI(3)
 $RANDI(4)
 $RANDI(5)
 $RANDI(6)
 $RANDI(7)
 $RANDI(8)
 $RANDI(9)
 $RANDI(10)
 $RANDI(11)
 $RANDI(12)
 $RANDI(13)
 $RANDI(14)
 $RANDI(15)

 asig    rand    10000, .5, 1
 asig    butlp   asig, 5000
 asig    dconv   asig, isize, itable
      out     asig *.5
 endin
 /* dconv.orc */

 /* dconv.sco */
 f1 0 16 10 1
 i1 0 10
 e
 /* dconv.sco */

Credits		~

Author: William "Pete" Moss 
2001                        

New in version 4.12

------------------------------------------------------------------------------
*delay*
delay	~

delay --  Delays an input signal by some time interval.

Description		~

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

Syntax		~

ar delay asig, idlt [, iskip]

Initialization		~

idlt -- requested delay time in seconds. This can be as large as available
memory will permit. The space required for n seconds of delay is 4n * sr
bytes. It is allocated at the time the instrument is first initialized, and
returned to the pool at the end of a score section.

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

Performance		~

asig -- audio signal

delay is a composite of |delayr| delayr and |delayw| delayw, both reading
from and writing into its own storage area. It can thus accomplish signal
time-shift, although modified feedback is not possible. There is no minimum
delay period.

Examples		~

Here is an example of the delay opcode. It uses the files delay.orc and
delay.sco.

Example 1. Example of the delay opcode.

 /* delay.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 2

 ; Instrument #1 -- Delayed beeps.
 instr 1
; Make a basic sound.
abeep vco 20000, 440, 1

; Delay the beep by .1 seconds.
idlt = 0.1
adel delay abeep, idlt

; Send the beep to the left speaker and
; the delayed beep to the right speaker.
outs abeep, adel
 endin
 /* delay.orc */

 /* delay.sco */
 /* Written by Kevin Conder */
 ; Table #1, a sine wave.
 f 1 0 16384 10 1

 ; Keep the score running for 2 seconds.
 f 0 2

 ; Play Instrument #1.
 i 1 0.0 0.2
 i 1 0.5 0.2
 e
 /* delay.sco */

See Also		~

|delay1| delay1, |delayr| delayr, |delayw| delayw

------------------------------------------------------------------------------
*delay1*
delay1	~

delay1 --  Delays an input signal by one sample.

Description		~

Delays an input signal by one sample.

Syntax		~

ar delay1 asig [, iskip]

Initialization		~

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

Performance		~

delay1 is a special form of delay that serves to delay the audio signal asig
by just one sample. It is thus functionally equivalent to the |delay| delay
opcode but is more efficient in both time and space. This unit is
particularly useful in the fabrication of generalized non-recursive filters.

See Also		~

|delay| delay, |delayr| delayr, |delayw| delayw

------------------------------------------------------------------------------
*delayr*
delayr	~

delayr --  Reads from an automatically established digital delay line.

Description		~

Reads from an automatically established digital delay line.

Syntax		~

ar delayr idlt [, iskip]

Initialization		~

idlt -- requested delay time in seconds. This can be as large as available
memory will permit. The space required for n seconds of delay is 4n * sr
bytes. It is allocated at the time the instrument is first initialized, and
returned to the pool at the end of a score section.

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

Performance		~

delayr reads from an automatically established digital delay line, in which
the signal retrieved has been resident for idlt seconds. This unit must be
paired with and precede an accompanying |delayw| delayw unit. Any other
Csound statements can intervene.

Examples		~

See the example for |delayw| delayw.

See Also		~

|delay| delay, |delay1| delay1, |delayw| delayw

------------------------------------------------------------------------------
*delayw*
delayw	~

delayw --  Writes the audio signal to a digital delay line.

Description		~

Writes the audio signal to a digital delay line.

Syntax		~

delayw asig

Performance		~

delayw writes asig into the delay area established by the preceding |delayr|
delayr unit. Viewed as a pair, these two units permit the formation of
modified feedback loops, etc. However, there is a lower bound on the value of
idlt, which must be at least 1 control period (or 1/kr).

Examples		~

Here is an example of the delayw opcode. It uses the files delayw.orc and
delayw.sco.

Example 1. Example of the delayw opcode.

 /* delayw.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 2

 ; Instrument #1 -- Delayed beeps.
 instr 1
; Make a basic sound.
abeep vco 20000, 440, 1

; Set up a delay line.
idlt = 0.1
adel delayr idlt

; Write the beep to the delay line.
delayw abeep

; Send the beep to the left speaker and
; the delayed beep to the right speaker.
outs abeep, adel
 endin
 /* delayw.orc */

 /* delayw.sco */
 /* Written by Kevin Conder */
 ; Table #1, a sine wave.
 f 1 0 16384 10 1

 ; Keep the score running for 2 seconds.
 f 0 2

 ; Play Instrument #1.
 i 1 0.0 0.2
 i 1 0.5 0.2
 e
 /* delayw.sco */

See Also		~

|delay| delay, |delay1| delay1, |delayr| delayr

------------------------------------------------------------------------------
*deltap*
deltap	~

deltap --  Taps a delay line at variable offset times.

Description		~

Tap a delay line at variable offset times.

Syntax		~

ar deltap kdlt

Performance		~

kdlt -- specifies the tapped delay time in seconds. Each can range from 1
control period to the full delay time of the read/write pair; however, since
there is no internal check for adherence to this range, the user is wholly
responsible. Each argument can be a constant, a variable, or a time-varying
signal.

deltap extracts sound by reading the stored samples directly.

This opcode can tap into a |delayr| delayr/|delayw| delayw pair, extracting
delayed audio from the idlt seconds of stored sound. There can be any number
of deltap and/or |deltapi| deltapi units between a read/write pair. Each
receives an audio tap with no change of original amplitude.

This opcode can provide multiple delay taps for arbitrary delay path and
feedback networks. They can deliver either constant-time or time-varying
taps, and are useful for building chorus effects, harmonizers, and Doppler
shifts. Constant-time delay taps (and some slowly changing ones) do not need
interpolated readout; they are well served by deltap. Medium-paced or fast
varying dlt's, however, will need the extra services of deltapi.

delayr/delayw pairs may be interleaved. To associate a delay tap unit with a
specific delayr unit, it not only has to be located between that delayr and
the appropriate delayw unit, but must also precede any following delayr
units. See Example 2. (This feature added in Csound version 3.57 by Jens Groh
and John ffitch).

N.B. k-rate delay times are not internally interpolated, but rather lay down
stepped time-shifts of audio samples; this will be found quite adequate for
slowly changing tap times. For medium to fast-paced changes, however, one
should provide a higher resolution audio-rate timeshift as input.

Examples		~

Example 1. deltap example #1

asource  buzz      1, 440, 20, 1
atime    linseg    1, p3/2,.01, p3/2,1   ; trace a distance in secs
ampfac   =         1/atime/atime         ; and calc an amp factor
adump    delayr    1                     ; set maximum distance
amove    deltapi   atime                 ; move sound source past
         delayw    asource               ; the listener
         out       amove * ampfac

Example 2. deltap example #2

ainput1 =     .....
ainput2 =     .....
kdlyt1  =     .....
kdlyt2  =     .....

 ;Read delayed signal, first delayr instance:
adump   delayr  4.0
adly1   deltap  kdlyt1       ;associated with first delayr instance

 ;Read delayed signal, second delayr instance:
adump   delayr  4.0
adly2   deltap  kdlyt2       ; associated with second delayr instance

 ;Do some cross-coupled manipulation:
afdbk1  =       0.7 * adly1 + 0.7 * adly2 + ainput1
afdbk2  =       -0.7 * adly1 + 0.7 * adly2 + ainput2

 ;Feed back signal, associated with first delayr instance:
        delayw  afdbk1

 ;Feed back signal, associated with second delayr instance:
        delayw  afdbk2
        outs    adly1, adly2

See Also		~

|deltap3| deltap3, |deltapi| deltapi, |deltapn| deltapn

------------------------------------------------------------------------------
*deltap3*
deltap3	~

deltap --  Taps a delay line at variable offset times, uses cubic
interpolation.

Description		~

Taps a delay line at variable offset times, uses cubic interpolation.

Syntax		~

ar deltap3 xdlt

Performance		~

xdlt -- specifies the tapped delay time in seconds. Each can range from 1
control period to the full delay time of the read/write pair; however, since
there is no internal check for adherence to this range, the user is wholly
responsible. Each argument can be a constant, a variable, or a time-varying
signal; the xdlt argument in deltap3 implies that an audio-varying delay is
permitted there.

deltap3 is experimental, and uses cubic interpolation. (New in Csound version
3.50.)

This opcode can tap into a |delayr| delayr/|delayw| delayw pair, extracting
delayed audio from the idlt seconds of stored sound. There can be any number
of deltap and/or deltapi units between a read/write pair. Each receives an
audio tap with no change of original amplitude.

This opcode can provide multiple delay taps for arbitrary delay path and
feedback networks. They can deliver either constant-time or time-varying
taps, and are useful for building chorus effects, harmonizers, and Doppler
shifts. Constant-time delay taps (and some slowly changing ones) do not need
interpolated readout; they are well served by deltap. Medium-paced or fast
varying dlt's, however, will need the extra services of deltapi.

delayr/delayw pairs may be interleaved. To associate a delay tap unit with a
specific delayr unit, it not only has to be located between that delayr and
the appropriate delayw unit, but must also precede any following delayr
units. See Example 2. (This feature added in Csound version 3.57 by Jens Groh
and John ffitch).

N.B. k-rate delay times are not internally interpolated, but rather lay down
stepped time-shifts of audio samples; this will be found quite adequate for
slowly changing tap times. For medium to fast-paced changes, however, one
should provide a higher resolution audio-rate timeshift as input.

Examples		~

Example 1. deltap example #1

asource  buzz      1, 440, 20, 1
atime    linseg    1, p3/2,.01, p3/2,1   ; trace a distance in secs
ampfac   =         1/atime/atime         ; and calc an amp factor
adump    delayr    1                     ; set maximum distance
amove    deltapi   atime                 ; move sound source past
         delayw    asource               ; the listener
         out       amove * ampfac

Example 2. deltap example #2

ainput1 =     .....
ainput2 =     .....
kdlyt1  =     .....
kdlyt2  =     .....

 ;Read delayed signal, first delayr instance:
adump   delayr  4.0
adly1   deltap  kdlyt1       ;associated with first delayr instance

 ;Read delayed signal, second delayr instance:
adump   delayr  4.0
adly2   deltap  kdlyt2       ; associated with second delayr instance

 ;Do some cross-coupled manipulation:
afdbk1  =       0.7 * adly1 + 0.7 * adly2 + ainput1
afdbk2  =       -0.7 * adly1 + 0.7 * adly2 + ainput2

 ;Feed back signal, associated with first delayr instance:
        delayw  afdbk1

 ;Feed back signal, associated with second delayr instance:
        delayw  afdbk2
        outs    adly1, adly2

See Also		~

|deltap| deltap, |deltapi| deltapi, |deltapn| deltapn

------------------------------------------------------------------------------
*deltapi*
deltapi	~

deltapi --  Taps a delay line at variable offset times, uses interpolation.

Description		~

Taps a delay line at variable offset times, uses interpolation.

Syntax		~

ar deltapi xdlt

Performance		~

xdlt -- specifies the tapped delay time in seconds. Each can range from 1
control period to the full delay time of the read/write pair; however, since
there is no internal check for adherence to this range, the user is wholly
responsible. Each argument can be a constant, a variable, or a time-varying
signal; the xdlt argument in deltapi implies that an audio-varying delay is
permitted there.

deltapi extracts sound by interpolated readout. By interpolating between
adjacent stored samples deltapi represents a particular delay time with more
accuracy, but it will take about twice as long to run.

This opcode can tap into a |delayr| delayr/|delayw| delayw pair, extracting
delayed audio from the idlt seconds of stored sound. There can be any number
of |deltap| deltap and/or deltapi units between a read/write pair. Each
receives an audio tap with no change of original amplitude.

This opcode can provide multiple delay taps for arbitrary delay path and
feedback networks. They can deliver either constant-time or time-varying
taps, and are useful for building chorus effects, harmonizers, and Doppler
shifts. Constant-time delay taps (and some slowly changing ones) do not need
interpolated readout; they are well served by deltap. Medium-paced or fast
varying dlt's, however, will need the extra services of deltapi.

delayr/delayw pairs may be interleaved. To associate a delay tap unit with a
specific delayr unit, it not only has to be located between that delayr and
the appropriate delayw unit, but must also precede any following delayr
units. See Example 2. (This feature added in Csound version 3.57 by Jens Groh
and John ffitch).

N.B. k-rate delay times are not internally interpolated, but rather lay down
stepped time-shifts of audio samples; this will be found quite adequate for
slowly changing tap times. For medium to fast-paced changes, however, one
should provide a higher resolution audio-rate timeshift as input.

Examples		~

Example 1. deltap example #1

asource  buzz      1, 440, 20, 1
atime    linseg    1, p3/2,.01, p3/2,1   ; trace a distance in secs
ampfac   =         1/atime/atime         ; and calc an amp factor
adump    delayr    1                     ; set maximum distance
amove    deltapi   atime                 ; move sound source past
         delayw    asource               ; the listener
         out       amove * ampfac

Example 2. deltap example #2

ainput1 =     .....
ainput2 =     .....
kdlyt1  =     .....
kdlyt2  =     .....

 ;Read delayed signal, first delayr instance:
adump   delayr  4.0
adly1   deltap  kdlyt1       ;associated with first delayr instance

 ;Read delayed signal, second delayr instance:
adump   delayr  4.0
adly2   deltap  kdlyt2       ; associated with second delayr instance

 ;Do some cross-coupled manipulation:
afdbk1  =       0.7 * adly1 + 0.7 * adly2 + ainput1
afdbk2  =       -0.7 * adly1 + 0.7 * adly2 + ainput2

 ;Feed back signal, associated with first delayr instance:
        delayw  afdbk1

 ;Feed back signal, associated with second delayr instance:
        delayw  afdbk2
        outs    adly1, adly2

See Also		~

|deltap| deltap, |deltap3| deltap3, |deltapn| deltapn

------------------------------------------------------------------------------
*deltapn*
deltapn	~

deltapn --  Taps a delay line at variable offset times.

Description		~

Tap a delay line at variable offset times.

Syntax		~

ar deltapn xnumsamps

Performance		~

xnumsamps -- specifies the tapped delay time in number of samples. Each can
range from 1 control period to the full delay time of the read/write pair;
however, since there is no internal check for adherence to this range, the
user is wholly responsible. Each argument can be a constant, a variable, or a
time-varying signal.

deltapn is identical to |deltapi| deltapi, except delay time is specified in
number of samples, instead of seconds (Hans Mikelson).

This opcode can tap into a delayr/delayw pair, extracting delayed audio from
the idlt seconds of stored sound. There can be any number of deltap and/or
deltapi units between a read/write pair. Each receives an audio tap with no
change of original amplitude.

This opcode can provide multiple delay taps for arbitrary delay path and
feedback networks. They can deliver either constant-time or time-varying
taps, and are useful for building chorus effects, harmonizers, and Doppler
shifts. Constant-time delay taps (and some slowly changing ones) do not need
interpolated readout; they are well served by deltap. Medium-paced or fast
varying dlt's, however, will need the extra services of deltapi.

delayr/delayw pairs may be interleaved. To associate a delay tap unit with a
specific delayr unit, it not only has to be located between that delayr and
the appropriate delayw unit, but must also precede any following delayr
units. See Example 2. (This feature added in Csound version 3.57 by Jens Groh
and John ffitch).

N.B. k-rate delay times are not internally interpolated, but rather lay down
stepped time-shifts of audio samples; this will be found quite adequate for
slowly changing tap times. For medium to fast-paced changes, however, one
should provide a higher resolution audio-rate timeshift as input.

Examples		~

Example 1. deltap example #1

asource  buzz      1, 440, 20, 1
atime    linseg    1, p3/2,.01, p3/2,1   ; trace a distance in secs
ampfac   =         1/atime/atime         ; and calc an amp factor
adump    delayr    1                     ; set maximum distance
amove    deltapi   atime                 ; move sound source past
         delayw    asource               ; the listener
         out       amove * ampfac

Example 2. deltap example #2

ainput1 =     .....
ainput2 =     .....
kdlyt1  =     .....
kdlyt2  =     .....

 ;Read delayed signal, first delayr instance:
adump   delayr  4.0
adly1   deltap  kdlyt1       ;associated with first delayr instance

 ;Read delayed signal, second delayr instance:
adump   delayr  4.0
adly2   deltap  kdlyt2       ; associated with second delayr instance

 ;Do some cross-coupled manipulation:
afdbk1  =       0.7 * adly1 + 0.7 * adly2 + ainput1
afdbk2  =       -0.7 * adly1 + 0.7 * adly2 + ainput2

 ;Feed back signal, associated with first delayr instance:
        delayw  afdbk1

 ;Feed back signal, associated with second delayr instance:
        delayw  afdbk2
        outs    adly1, adly2

See Also		~

|deltap| deltap, |deltap3| deltap3, |deltapi| deltapi

------------------------------------------------------------------------------
*deltapx*
deltapx	~

deltapx --  Read to or write from a delay line with interpolation.

Description		~

deltapx is similar to |deltapi| deltapi or |deltap3| deltap3. However, it
allows higher quality interpolation. This opcode can read from and write to a
delayr/delayw delay line with interpolation.

Syntax		~

aout deltapx adel, iwsize

Initialization		~

iwsize -- interpolation window size in samples. Allowed values are integer
multiplies of 4 in the range 4 to 1024. iwsize = 4 uses cubic interpolation.
Increasing iwsize improves sound quality at the expense of CPU usage, and
minimum delay time.

Performance		~

aout -- Output signal

adel -- Delay time in seconds.

 a1      delayr idlr
      deltapxw a2, adl1, iws1
 a3      deltapx adl2, iws2
      deltapxw a4, adl3, iws3
      delayw a5

Minimum and maximum delay times:

 idlr >= 1/kr                                Delay line length
 adl1 >= (iws1/2)/sr                         Write before read
 adl1 <= idlr - (1 + iws1/2)/sr              (allows shorter delays)
 adl2 >= 1/kr + (iws2/2)/sr                  Read time
 adl2 <= idlr - (1 + iws2/2)/sr
 adl2 >= adl1 + (iws1 + iws2) / (2*sr)
 adl2 >= 1/kr + adl3 + (iws2 + iws3) / (2*sr)
 adl3 >= (iws3/2)/sr                         Write after read
 adl3 <= idlr - (1 + iws3/2)/sr              (allows feedback)

  Note                                                                        
  Window sizes for opcodes other than deltapx are: deltap, deltapn: 1,        
  deltapi: 2 (linear), deltap3: 4 (cubic)                                     

Examples		~

 a1      phasor 300.0
 a1      =  a1 - 0.5
 a_      delayr 1.0
 adel    phasor 4.0
 adel    =  sin (2.0 * 3.14159265 * adel) * 0.01 + 0.2
      deltapxw a1, adel, 32
 adel    phasor 2.0
 adel    =  sin (2.0 * 3.14159265 * adel) * 0.01 + 0.2
      deltapxw a1, adel, 32
 adel    =  0.3
 a2      deltapx adel, 32
 a1      =  0
      delayw a1
      out a2 * 20000.0

See Also		~

|deltapxw| deltapxw

Credits		~

Author: Istvan Varga 
August 2001          

New in version 4.13

------------------------------------------------------------------------------
*deltapxw*
deltapxw	~

deltapxw --  Mixes the input signal to a delay line.

Description		~

deltapxw mixes the input signal to a delay line. This opcode can be mixed
with reading units (|deltap| deltap, |deltapn| deltapn, |deltapi| deltapi,
|deltap3| deltap3, and |deltapx| deltapx) in any order; the actual delay time
is the difference of the read and write time. This opcode can read from and
write to a |delayr| delayr/|delayw| delayw delay line with interpolation.

Syntax		~

deltapxw ain, adel, iwsize

Initialization		~

iwsize -- interpolation window size in samples. Allowed values are integer
multiplies of 4 in the range 4 to 1024. iwsize = 4 uses cubic interpolation.
Increasing iwsize improves sound quality at the expense of CPU usage, and
minimum delay time.

Performance		~

ain -- Input signal

adel -- Delay time in seconds.

 a1      delayr idlr
      deltapxw a2, adl1, iws1
 a3      deltapx adl2, iws2
      deltapxw a4, adl3, iws3
      delayw a5

Minimum and maximum delay times:

 idlr >= 1/kr                                Delay line length
 adl1 >= (iws1/2)/sr                         Write before read
 adl1 <= idlr - (1 + iws1/2)/sr              (allows shorter delays)
 adl2 >= 1/kr + (iws2/2)/sr                  Read time
 adl2 <= idlr - (1 + iws2/2)/sr
 adl2 >= adl1 + (iws1 + iws2) / (2*sr)
 adl2 >= 1/kr + adl3 + (iws2 + iws3) / (2*sr)
 adl3 >= (iws3/2)/sr                         Write after read
 adl3 <= idlr - (1 + iws3/2)/sr              (allows feedback)

  Note                                                                        
  Window sizes for opcodes other than deltapx are: deltap, deltapn: 1,        
  deltapi: 2 (linear), deltap3: 4 (cubic)                                     

Examples		~

 a1      phasor 300.0
 a1      =  a1 - 0.5
 a_      delayr 1.0
 adel    phasor 4.0
 adel    =  sin (2.0 * 3.14159265 * adel) * 0.01 + 0.2
      deltapxw a1, adel, 32
 adel    phasor 2.0
 adel    =  sin (2.0 * 3.14159265 * adel) * 0.01 + 0.2
      deltapxw a1, adel, 32
 adel    =  0.3
 a2      deltapx adel, 32
 a1      =  0
      delayw a1
      out a2 * 20000.0

See Also		~

|deltapx| deltapx

Credits		~

Author: Istvan Varga 
August 2001          

New in version 4.13

------------------------------------------------------------------------------
*diff*
diff	~

diff --  Modify a signal by differentiation.

Description		~

Modify a signal by differentiation.

Syntax		~

ar diff asig [, iskip]

kr diff ksig [, iskip]

Initialization		~

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

Performance		~

|integ| integ and diff perform integration and differentiation on an input
control signal or audio signal. Each is the converse of the other, and
applying both will reconstruct the original signal. Since these units are
special cases of low-pass and high-pass filters, they produce a scaled (and
phase shifted) output that is frequency-dependent. Thus diff of a sine
produces a cosine, with amplitude 2 * sin(pi * Hz / sr) that of the original
(for each component partial); integ will inversely affect the magnitudes of
its component inputs. With this understanding, these units can provide useful
signal modification.

Examples		~

Here is an example of the diff opcode. It uses the files diff.orc and
diff.sco.

Example 1. Example of the diff opcode.

 /* diff.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1 -- a normal instrument.
 instr 1
; Generate a band-limited pulse train.
asrc buzz 20000, 440, 20,  1

out asrc
 endin

 ; Instrument #2 -- a differentiated instrument.
 instr 2
; Generate a band-limited pulse train.
asrc buzz 20000, 440, 20,  1

; Emphasize the highs.
a1 diff asrc

out a1
 endin
 /* diff.orc */

 /* diff.sco */
 /* Written by Kevin Conder */
 ; Table #1, a sine wave.
 f 1 0 16384 10 1

 ; Play Instrument #1 for one second.
 i 1 0 1
 ; Play Instrument #2 for one second.
 i 2 1 1
 e
 /* diff.sco */

See Also		~

|downsamp| downsamp, |integ| integ, |interp| interp, |samphold| samphold,
|upsamp| upsamp

------------------------------------------------------------------------------
*diskin*
diskin	~

diskin --  Reads audio data from an external device or stream and can alter
its pitch.

Description		~

Reads audio data from an external device or stream and can alter its pitch.

Syntax		~

ar1 [,ar2] [, ar3] [, ar4] diskin ifilcod, kpitch [, iskiptim] [,
iwraparound] [, iformat]

Initialization		~

ifilcod -- integer or character-string denoting the source soundfile name. An
integer denotes the file soundin.filcod ; a character-string (in double
quotes, spaces permitted) gives the filename itself, optionally a full
pathname. If not a full path, the named file is sought first in the current
directory, then in that given by the environment variable SSDIR (if defined)
then by SFDIR. See also |gen01| GEN01.

iskptim (optional) -- time in seconds of input sound to be skipped. The
default value is 0.

iformat (optional) -- specifies the audio data file format:

  * 1 = 8-bit signed char (high-order 8 bits of a 16-bit integer)

  * 2 = 8-bit A-law bytes

  * 3 = 8-bit U-law bytes

  * 4 = 16-bit short integers

  * 5 = 32-bit long integers

  * 6 = 32-bit floats

iwraparound -- 1 = on, 0 = off (wraps around to end of file either direction)

If iformat = 0 it is taken from the soundfile header, and if no header from
the Csound |flagsminuslowero| -o command-line flag. The default value is 0.

Performance		~

kpitch -- can be any real number. a negative number signifies backwards
playback. The given number is a pitch ratio, where:

  * 1 = normal pitch

  * 2 = 1 octave higher

  * 3 = 12th higher, etc.

  * .5 = 1 octave lower

  * .25 = 2 octaves lower, etc.

  * -1 = normal pitch backwards

  * -2 = 1 octave higher backwards, etc.

diskin is identical to |soundin| soundin except that it can alter the pitch
of the sound that is being read.

  Note to Windows users                                                       
  Windows users typically use back-slashes, "\", when specifying the paths of 
  their files. As an example, a Windows user might use the path               
  "c:\music\samples\loop001.wav". This is problematic because back-slashes    
  are normally used to specify special characters.                            
  To correctly specify this path in Csound, one may alternately:              
    * Use forward slashes: c:/music/samples/loop001.wav                       
    * Use back-slash special characters, "\\":                                
      c:\\music\\samples\\loop001.wav                                         

Examples		~

Here is an example of the diskin opcode. It uses the files diskin.orc,
diskin.sco, beats.wav.

Example 1. Example of the diskin opcode.

 /* diskin.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 44100
 ksmps = 1
 nchnls = 1

 ; Instrument #1 - play an audio file.
 instr 1
; Play the audio file backwards.
asig diskin "beats.wav", -1
out asig
 endin
 /* diskin.orc */

 /* diskin.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1, the audio file, for three seconds.
 i 1 0 3
 e
 /* diskin.sco */

See Also		~

|in| in, |inh| inh, |ino| ino, |inq| inq, |ins| ins, |soundin| soundin

Credits		~

Authors: Barry L. Vercoe, Matt Ingalls/Mike Berry 
MIT, Mills College                                
1993-1997                                         

Warning to Windows users added by Kevin Conder, April 2002

------------------------------------------------------------------------------
*dispfft*
dispfft	~

displayfft --  Displays the Fourier Transform of an audio or control signal.

Description		~

These units will print orchestra init-values, or produce graphic display of
orchestra control signals and audio signals. Uses X11 windows if enabled,
else (or if |flagsminuslowerg| -g flag is set) displays are approximated in
ASCII characters.

Syntax		~

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

Initialization		~

iprd -- the period of display in seconds.

iwsiz -- size of the input window in samples. A window of iwsiz points will
produce a Fourier transform of iwsiz/2 points, spread linearly in frequency
from 0 to sr/2. iwsiz must be a power of 2, with a minimum of 16 and a
maximum of 4096. The windows are permitted to overlap.

iwtyp (optional, default=0) -- window type. 0 = rectangular, 1 = Hanning. The
default value is 0 (rectangular).

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

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

Performance		~

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

Examples		~

Here is an example of the dispfft opcode. It uses the files dispfft.orc,
dispfft.sco and beats.wav.

Example 1. Example of the dispfft opcode.

 /* dispfft.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
asig soundin "beats.wav"
dispfft asig, 1, 512
out asig
 endin
 /* dispfft.orc */

 /* dispfft.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for three seconds.
 i 1 0 3
 e
 /* dispfft.sco */

See Also		~

|display| display, |print| print

Credits		~

Comments about the inprds parameter contributed by Rasmus Ekman.

------------------------------------------------------------------------------
*display*
display	~

display --  Displays the audio or control signals as an amplitude vs. time
graph.

Description		~

These units will print orchestra init-values, or produce graphic display of
orchestra control signals and audio signals. Uses X11 windows if enabled,
else (or if |flagsminuslowerg| -g flag is set) displays are approximated in
ASCII characters.

Syntax		~

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

Initialization		~

iprd -- the period of display in seconds.

inprds (optional, default=1) -- Number of display periods retained in each
display graph. A value of 2 or more will provide a larger perspective of the
signal motion. The default value is 1 (each graph completely new).

inprds (optional, default=1) -- a scaling factor for the displayed waveform,
controlling how many iprd-sized frames of samples are drawn in the window
(the default and minimum value is 1.0). Higher inprds values are slower to
draw (more points to draw) but will show the waveform scrolling through the
window, which is useful with low iprd values.

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

Performance		~

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

Examples		~

Here is an example of the display opcode. It uses the files display.orc and
display.sco.

Example 1. Example of the display opcode.

 /* display.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Go from 1000 to 0 linearly, over the period defined by p3.
klin line 1000, p3, 0

; Create a new display each second, wait for the user.
display klin, 1, 1, 1
 endin
 /* display.orc */

 /* display.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for 5 seconds.
 i 1 0 5
 e
 /* display.sco */

See Also		~

|dispfft| dispfft, |print| print

Credits		~

Comments about the inprds parameter contributed by Rasmus Ekman.

------------------------------------------------------------------------------
*distort1*
distort1	~

distort1 --  Modified hyperbolic tangent distortion.

Description		~

Implementation of modified hyperbolic tangent distortion. distort1 can be
used to generate wave shaping distortion based on a modification of the
|tanh| tanh function.

         exp(asig * (pregain + shape1)) - exp(asig*(pregain+shape2))
  aout = -----------------------------------------------------------
         exp(asig*pregain)              + exp(-asig*pregain)

Syntax		~

ar distort1 asig, kpregain, kpostgain, kshape1, kshape2

Performance		~

asig - is the input signal.

kpregain -- determines the amount of gain applied to the signal before
waveshaping. A value of 1 gives slight distortion.

kpostgain -- determines the amount of gain applied to the signal after
waveshaping.

kshape1 -- determines the shape of the positive part of the curve. A value of
0 gives a flat clip, small positive values give sloped shaping.

kshape2 -- determines the shape of the negative part of the curve.

Examples		~

Here is an example of the distort1 opcode. It uses the files distort1.orc and
distort1.sco.

Example 1. Example of the distort1 opcode.

 /* distort1.orc */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 2

 gadist  init 0

 instr 1
iamp    =        p4
ifqc    =        cpspch(p5)
asig    pluck iamp, ifqc, ifqc, 0, 1
gadist  =       gadist + asig
 endin

 instr 50
kpre    init p4
kpost   init p5
kshap1  init p6
kshap2  init p7
aout    distort1 gadist, kpre, kpost, kshap1, kshap2

outs     aout, aout

gadist  =        0
 endin
 /* distort1.orc */

 /* distort1.sco */
 ;   Sta  Dur  Amp    Pitch
 i1  0.0  3.0  10000  6.00
 i1  0.5  2.5  10000  7.00
 i1  1.0  2.0  10000  7.07
 i1  1.5  1.5  10000  8.00

 ;   Sta  Dur  PreGain PostGain Shape1 Shape2
 i50 0    3    2       1        0      0
 e
 /* distort1.sco */

Credits		~

Author: Hans Mikelson 
December 1998         

New in Csound version 3.50

------------------------------------------------------------------------------
*divz*
divz	~

divz --  Safely divides two numbers.

Syntax		~

ar divz xa, xb, ksubst

ir divz ia, ib, isubst

kr divz ka, kb, ksubst

Description		~

Safely divides two numbers.

Initialization		~

Whenever b is not zero, set the result to the value a / b; when b is zero,
set it to the value of subst instead.

Examples		~

Here is an example of the divz opcode. It uses the files divz.orc and
divz.sco.

Example 1. Example of the divz opcode.

 /* divz.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Define the numbers to be divided.
ka init 200
; Linearly change the value of kb from 200 to 0.
kb line 0, p3, 200
; If a "divide by zero" error occurs, substitute -1.
ksubst init -1

; Safely divide the numbers.
kresults divz ka, kb, ksubst

; Print out the results.
printks "%f / %f = %f\\n", 0.1, ka, kb, kresults
 endin
 /* divz.orc */

 /* divz.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* divz.sco */

Its output should include lines like:

 200.000000 / 0.000000 = -1.000000
 200.000000 / 19.999887 = 10.000056
 200.000000 / 40.000027 = 4.999997

See Also		~

|assign| =, |init| init, |tival| tival

------------------------------------------------------------------------------
*downsamp*
downsamp	~

downsamp --  Modify a signal by down-sampling.

Description		~

Modify a signal by down-sampling.

Syntax		~

kr downsamp asig [, iwlen]

Initialization		~

iwlen (optional) -- window length in samples over which the audio signal is
averaged to determine a downsampled value. Maximum length is ksmps; 0 and 1
imply no window averaging. The default value is 0.

Performance		~

downsamp converts an audio signal to a control signal by downsampling. It
produces one kval for each audio control period. The optional window invokes
a simple averaging process to suppress foldover.

Examples		~

Here is an example of the downsamp opcode. It uses the files downsamp.orc and
downsamp.sco.

Example 1. Example of the downsamp opcode.

 /* downsamp.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Create a noise signal at a-rate.
anoise noise 20000, 0.2

; Downsample the noise signal to k-rate.
knoise downsamp anoise

; Use the noise signal at k-rate.
a1 oscil 30000, knoise, 1
out anoise
 endin
 /* downsamp.orc */

 /* downsamp.sco */
 /* Written by Kevin Conder */
 ; Table #1, a sine wave.
 f 1 0 16384 10 1

 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* downsamp.sco */

See Also		~

|diff| diff, |integ| integ, |interp| interp, |samphold| samphold, |upsamp|
upsamp

------------------------------------------------------------------------------
*dripwater*
dripwater	~

dripwater --  Semi-physical model of a water drop.

Description		~

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

Syntax		~

ar dripwater kamp, idettack [, inum] [, idamp] [, imaxshake] [, ifreq] [,
ifreq1] [, ifreq2]

Initialization		~

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

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

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

damping_amount = 0.996 + (idamp * 0.002)

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

The recommended range for idamp is usually below 75% of the maximum value.
Rasmus Ekman suggests a range of 1.4-1.75. He also suggests a maximum value
of 1.9 instead of the theoretical limit of 2.0.

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

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

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

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

Performance		~

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

Examples		~

Here is an example of the dripwater opcode. It uses the files dripwater.orc
and dripwater.sco.

Example 1. Example of the dripwater opcode.

 /* dripwater.orc */
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 instr 01  ;example of a water drip
 a1  line 5, p3, 5  ;preset an amplitude boost
 a2  dripwater p4, 0.01, 0, .9  ;dripwater needs a little amplitude help at these values
 a3  product a1, a2 ;increase amplitude
  out a3
  endin
 /* dripwater.orc */

 /* dripwater.sco */
 i1 0 1 20000
 e
 /* dripwater.sco */

See Also		~

|bamboo| bamboo, |guiro| guiro, |sleighbells| sleighbells, |tambourine|
tambourine

Credits		~

Author: Perry Cook, part of the PhISEM (Physically Informed Stochastic Event  
Modeling)                                                                     
Adapted by John ffitch                                                        
University of Bath, Codemist Ltd.                                             
Bath, UK                                                                      

New in Csound version 4.07

Added notes by Rasmus Ekman on May 2002.

------------------------------------------------------------------------------
*dumpk*
dumpk	~

dumpk --  Periodically writes an orchestra control-signal value to an
external file.

Description		~

Periodically writes an orchestra control-signal value to a named external
file in a specific format.

Syntax		~

dumpk ksig, ifilname, iformat, iprd

Initialization		~

ifilname -- character string (in double quotes, spaces permitted) denoting
the external file name. May either be a full path name with target directory
specified or a simple filename to be created within the current directory

iformat -- specifies the output data format:

  * 1 = 8-bit signed char(high order 8 bits of a 16-bit integer

  * 4 = 16-bit short integers

  * 5 = 32-bit long integers

  * 6 = 32-bit floats, 7=ASCII long integers

  * 8 = ASCII floats (2 decimal places)

Note that A-law and U-law output are not available, and that all formats
except the lsat two are binary. The output file contains no header
information.

iprd -- the period of ksig output i seconds, rounded to the nearest orchestra
control period. A value of 0 implies one control period (the enforced
minimum), which will create an output file sampled at the orchestra control
rate.

Performance		~

ksig -- a control-rate signal

This opcode allows a generated control signal value to be saved in a named
external file. The file contains no self-defining header information. But it
contains a regularly sampled time series, suitable for later input or
analysis. There may be any number of dumpk opcodes in an instrument or
orchestra but each must write to a different file.

Examples		~

 knum    =         knum+1                                               ; at each k-period
 ktemp   tempest   krms, .02, .1, 3, 2, 800, .005, 0, 60, 4, .1, .995   ;estimate the tempo
 koct    specptrk  wsig, 6, .9, 0                                       ;and the pitch
      dumpk3    knum, ktemp, cpsoct(koct), "what happened when", 8 0 ;& save them

See Also		~

|dumpk2| dumpk2, |dumpk3| dumpk3, |dumpk4| dumpk4, |readk| readk, |readk2|
readk2, |readk3| readk3, |readk4| readk4

------------------------------------------------------------------------------
*dumpk2*
dumpk2	~

dumpk2 --  Periodically writes two orchestra control-signal values to an
external file.

Description		~

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

Syntax		~

dumpk2 ksig1, ksig2, ifilname, iformat, iprd

Initialization		~

ifilname -- character string (in double quotes, spaces permitted) denoting
the external file name. May either be a full path name with target directory
specified or a simple filename to be created within the current directory

iformat -- specifies the output data format:

  * 1 = 8-bit signed char(high order 8 bits of a 16-bit integer

  * 4 = 16-bit short integers

  * 5 = 32-bit long integers

  * 6 = 32-bit floats, 7=ASCII long integers

  * 8 = ASCII floats (2 decimal places)

Note that A-law and U-law output are not available, and that all formats
except the lsat two are binary. The output file contains no header
information.

iprd -- the period of ksig output i seconds, rounded to the nearest orchestra
control period. A value of 0 implies one control period (the enforced
minimum), which will create an output file sampled at the orchestra control
rate.

Performance		~

ksig1, ksig2 -- control-rate signals.

This opcode allows two generated control signal values to be saved in a named
external file. The file contains no self-defining header information. But it
contains a regularly sampled time series, suitable for later input or
analysis. There may be any number of dumpk2 opcodes in an instrument or
orchestra but each must write to a different file.

Examples		~

 knum    =         knum+1                                               ; at each k-period
 ktemp   tempest   krms, .02, .1, 3, 2, 800, .005, 0, 60, 4, .1, .995   ;estimate the tempo
 koct    specptrk  wsig, 6, .9, 0                                       ;and the pitch
      dumpk3    knum, ktemp, cpsoct(koct), "what happened when", 8 0 ;& save them

See Also		~

|dumpk| dumpk, |dumpk3| dumpk3, |dumpk4| dumpk4, |readk| readk, |readk2|
readk2, |readk3| readk3, |readk4| readk4

------------------------------------------------------------------------------
*dumpk3*
dumpk3	~

dumpk3 --  Periodically writes three orchestra control-signal values to an
external file.

Description		~

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

Syntax		~

dumpk3 ksig1, ksig2, ksig3, ifilname, iformat, iprd

Initialization		~

ifilname -- character string (in double quotes, spaces permitted) denoting
the external file name. May either be a full path name with target directory
specified or a simple filename to be created within the current directory

iformat -- specifies the output data format:

  * 1 = 8-bit signed char(high order 8 bits of a 16-bit integer

  * 4 = 16-bit short integers

  * 5 = 32-bit long integers

  * 6 = 32-bit floats, 7=ASCII long integers

  * 8 = ASCII floats (2 decimal places)

Note that A-law and U-law output are not available, and that all formats
except the lsat two are binary. The output file contains no header
information.

iprd -- the period of ksig output i seconds, rounded to the nearest orchestra
control period. A value of 0 implies one control period (the enforced
minimum), which will create an output file sampled at the orchestra control
rate.

Performance		~

ksig1, ksig2, ksig3 -- control-rate signals

This opcode allows three generated control signal values to be saved in a
named external file. The file contains no self-defining header information.
But it contains a regularly sampled time series, suitable for later input or
analysis. There may be any number of dumpk3 opcodes in an instrument or
orchestra but each must write to a different file.

Examples		~

 knum    =         knum+1                                               ; at each k-period
 ktemp   tempest   krms, .02, .1, 3, 2, 800, .005, 0, 60, 4, .1, .995   ;estimate the tempo
 koct    specptrk  wsig, 6, .9, 0                                       ;and the pitch
      dumpk3    knum, ktemp, cpsoct(koct), "what happened when", 8 0 ;& save them

See Also		~

|dumpk| dumpk, |dumpk2| dumpk2, |dumpk4| dumpk4, |readk| readk, |readk2|
readk2, |readk3| readk3, |readk4| readk4

------------------------------------------------------------------------------
*dumpk4*
dumpk4	~

dumpk4 --  Periodically writes four orchestra control-signal values to an
external file.

Description		~

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

Syntax		~

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

Initialization		~

ifilname -- character string (in double quotes, spaces permitted) denoting
the external file name. May either be a full path name with target directory
specified or a simple filename to be created within the current directory

iformat -- specifies the output data format:

  * 1 = 8-bit signed char(high order 8 bits of a 16-bit integer

  * 4 = 16-bit short integers

  * 5 = 32-bit long integers

  * 6 = 32-bit floats, 7=ASCII long integers

  * 8 = ASCII floats (2 decimal places)

Note that A-law and U-law output are not available, and that all formats
except the lsat two are binary. The output file contains no header
information.

iprd -- the period of ksig output i seconds, rounded to the nearest orchestra
control period. A value of 0 implies one control period (the enforced
minimum), which will create an output file sampled at the orchestra control
rate.

Performance		~

ksig1, ksig2, ksig3, ksig4 -- control-rate signals

This opcode allows four generated control signal values to be saved in a
named external file. The file contains no self-defining header information.
But it contains a regularly sampled time series, suitable for later input or
analysis. There may be any number of dumpk4 opcodes in an instrument or
orchestra but each must write to a different file.

Examples		~

 knum    =         knum+1                                               ; at each k-period
 ktemp   tempest   krms, .02, .1, 3, 2, 800, .005, 0, 60, 4, .1, .995   ;estimate the tempo
 koct    specptrk  wsig, 6, .9, 0                                       ;and the pitch
      dumpk3    knum, ktemp, cpsoct(koct), "what happened when", 8 0 ;& save them

See Also		~

|dumpk| dumpk, |dumpk2| dumpk2, |dumpk3| dumpk3, |readk| readk, |readk2|
readk2, |readk3| readk3, |readk4| readk4

------------------------------------------------------------------------------
*duserrnd*
duserrnd	~

duserrnd --  Discrete USER-defined-distribution RaNDom generator.

Description		~

Discrete USER-defined-distribution RaNDom generator.

Syntax		~

aout duserrnd ktableNum

iout duserrnd itableNum

kout duserrnd ktableNum

Initialization		~

itableNum -- number of table containing the random-distribution function.
Such table is generated by the user. See |gen40| GEN40, |gen41| GEN41, and
|gen42| GEN42. The table length does not need to be a power of 2

Performance		~

ktableNum -- number of table containing the random-distribution function.
Such table is generated by the user. See |gen40| GEN40, |gen41| GEN41, and
|gen42| GEN42. The table length does not need to be a power of 2

duserrnd (discrete user-defined-distribution random generator) generates
random values according to a discrete random distribution created by the
user. The user can create the discrete distribution histogram by using
|gen41| 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| GEN41 for
more details).

When used as a function, the rate of generation depends by the rate type of
input variable XtableNum. In this case it can be embedded into any formula.
Table number can be varied at k-rate, allowing to change the distribution
histogram during the performance of a single note. duserrnd is designed be
used in algorithmic music generation.

duserrnd can also be used to generate values following a set of ranges of
probabilities by using distribution functions generated by GEN42 (See |gen42|
GEN42 for more details). In this case, in order to simulate continuous
ranges, the length of table XtableNum should be reasonably big, as duserrnd
does not interpolate between table elements.

For a tutorial about random distribution histograms and functions see:

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

See Also		~

|cuserrnd| cuserrnd, |urd| urd

Credits		~

Author: Gabriel Maldonado

New in Version 4.16

------------------------------------------------------------------------------
*else*
else	~

else --  Executes a block of code when an "if...then" condition is false.

Description		~

Executes a block of code when an "if...then" condition is false.

Syntax		~

else

Performance		~

else is used inside of a block of code between the |if| "if...then" and
|endif| endif opcodes. It defines which statements are executed when a
"if...then" condition is false. Only one else statement may occur and it must
be the last conditional statement before the endif opcode.

Examples		~

See the example for the |if| if opcode.

See Also		~

|elseif| elseif, |endif| endif, |goto| goto, |if| if, |igoto| igoto, |kgoto|
kgoto, |tigoto| tigoto, |timout| timout

Credits		~

New in version 4.21

------------------------------------------------------------------------------
*elseif*
elseif	~

elseif --  Defines another "if...then" condition when a "if...then" condition
is false.

Description		~

Defines another "if...then" condition when a "if...then" condition is false.

Syntax		~

elseif xa R xb then

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

Performance		~

elseif is used inside of a block of code between the |if| "if...then" and
|endif| endif opcodes. When a "if...then" condition is false, it defines
another "if...then" condition to be met. Any number of elseif statements are
allowed.

Examples		~

See the example for the |if| if opcode.

See Also		~

|else| else, |endif| endif, |goto| goto, |if| if, |igoto| igoto, |kgoto|
kgoto, |tigoto| tigoto, |timout| timout

Credits		~

New in version 4.21

------------------------------------------------------------------------------
*endif*
endif	~

endif --  Closes a block of code that begins with an "if...then" statement.

Description		~

Closes a block of code that begins with an |if| "if...then" statement.

Syntax		~

endif

Performance		~

Any block of code that begins with an |if| "if...then" statement must end
with an endif statement.

Examples		~

See the example for the |if| if opcode.

See Also		~

|elseif| elseif, |else| else, |goto| goto, |if| if, |igoto| igoto, |kgoto|
kgoto, |tigoto| tigoto, |timout| timout

Credits		~

New in version 4.21

------------------------------------------------------------------------------
*endin*
endin	~

endin --  Ends the current instrument block.

Description		~

Ends the current instrument block.

Syntax		~

endin

Initialization		~

Ends the current instrument block.

Instruments can be defined in any order (but they will always be both
initialized and performed in ascending instrument number order). Instrument
blocks cannot be nested (i.e. one block cannot contain another).

     Note                                                                     
     There may be any number of instrument blocks in an orchestra.            

Examples		~

Here is an example of the endin opcode. It uses the files endin.orc and
endin.sco.

Example 1. Example of the endin opcode.

 /* endin.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
iamp = 10000
icps = 440
iphs = 0

a1 oscils iamp, icps, iphs
out a1
 endin
 /* endin.orc */

 /* endin.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for 2 seconds.
 i 1 0 2
 e
 /* endin.sco */

See Also		~

|instr| instr

------------------------------------------------------------------------------
*endop*
endop	~

endop --  Marks the end of an user-defined opcode block.

Description		~

Marks the end of an user-defined opcode block.

Syntax		~

endop

Performance		~

The syntax of a user-defined opcode block is as follows:

opcode  name, outtypes, intypes
xinarg1 [, xinarg2] [, xinarg3] ... [xinargN]  xin
[setksmps  iksmps]
... the rest of the instrument's code.
xout  xoutarg1 [, xoutarg2] [, xoutarg3] ... [xoutargN]
endop

The new opcode can then be used with the usual syntax:

[xinarg1] [, xinarg2] ... [xinargN]  name  [xoutarg1] [, xoutarg2] ... [xoutargN] [, iksmps]

Examples		~

See the example for the |opcode| opcode opcode.

See Also		~

|opcode| opcode, |setksmps| setksmps, |xin| xin, |xout| xout

Credits		~

Author: Istvan Varga, 2002; based on code by Matt J. Ingalls

New in version 4.22

------------------------------------------------------------------------------
*envlpx*
envlpx	~

envlpx --  Applies an envelope consisting of 3 segments.

Description		~

envlpx -- apply an envelope consisting of 3 segments:

 1. stored function rise shape

 2. modified exponential pseudo steady state

 3. exponential decay

Syntax		~

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

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

Initialization		~

irise -- rise time in seconds. A zero or negative value signifies no rise
modification.

idur -- overall duration in seconds. A zero or negative value will cause
initialization to be skipped.

idec -- decay time in seconds. Zero means no decay. An idec > idur will cause
a truncated decay.

ifn -- function table number of stored rise shape with extended guard point.

iatss -- attenuation factor, by which the last value of the envlpx rise is
modified during the note's pseudo steady state. A factor greater than 1
causes an exponential growth and a factor less than 1 creates an exponential
decay. A factor of 1 will maintain a true steady state at the last rise
value. Note that this attenuation is not by fixed rate (as in a piano), but
is sensitive to a note's duration. However, if iatss is negative (or if
steady state < 4 k-periods) a fixed attenuation rate of abs(iatss) per second
will be used. 0 is illegal.

iatdec -- attenuation factor by which the closing steady state value is
reduced exponentially over the decay period. This value must be positive and
is normally of the order of .01. A large or excessively small value is apt to
produce a cutoff which is audible. A zero or negative value is illegal.

ixmod (optional, between +- .9 or so) -- exponential curve modifier,
influencing the steepness of the exponential trajectory during the steady
state. Values less than zero will cause an accelerated growth or decay
towards the target (e.g. subito piano). Values greater than zero will cause a
retarded growth or decay. The default value is zero (unmodified exponential).

Performance		~

kamp, xamp -- input amplitude signal.

Rise modifications are applied for the first irise seconds, and decay from
time idur - idec. If these periods are separated in time there will be a
steady state during which amp will be modified by the first exponential
pattern. If the rise and decay periods overlap then that will cause a
truncated decay. If the overall duration idur is exceeded in performance, the
final decay will continue on in the same direction, tending asymptotically to
zero.

Examples		~

Here is an example of the envlpx opcode. It uses the files envlpx.orc and
envlpx.sco.

Example 1. Example of the envlpx opcode.

 /* envlpx.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1 - a simple instrument.
 instr 1
; Set the amplitude.
kamp init 20000
; Get the frequency from the fourth p-field.
kcps = cpspch(p4)

a1 vco kamp, kcps, 1
out a1
 endin

 ; Instrument #2 - instrument with an amplitude envelope.
 instr 2
kamp = 20000
irise = 0.05
idur = p3 - .01
idec = 0.5
ifn = 2
iatss = 1
iatdec = 0.01

; Create an amplitude envelope.
kenv envlpx kamp, irise, idur, idec, ifn, iatss, iatdec

; Get the frequency from the fourth p-field.
kcps = cpspch(p4)

a1 vco kenv, kcps, 1
out a1
 endin
 /* envlpx.orc */

 /* envlpx.sco */
 /* Written by Kevin Conder */
 ; Table #1, a sine wave.
 f 1 0 16384 10 1
 ; Table #2, a rising envelope.
 f 2 0 129 -7 0 128 1

 ; Set the tempo to 120 beats per minute.
 t 0 120

 ; Make sure the score plays for 33 seconds.
 f 0 33

 ; Play a melody with Instrument #1.
 ; p4 = frequency in pitch-class notation.
 i  1  0   1  8.04
 i  1  1   1  8.04
 i  1  2   1  8.05
 i  1  3   1  8.07
 i  1  4   1  8.07
 i  1  5   1  8.05
 i  1  6   1  8.04
 i  1  7   1  8.02
 i  1  8   1  8.00
 i  1  9   1  8.00
 i  1  10  1  8.02
 i  1  11  1  8.04
 i  1  12  2  8.04
 i  1  14  2  8.02

 ; Repeat the melody with Instrument #2.
 ; p4 = frequency in pitch-class notation.
 i  2  16  1  8.04
 i  2  17  1  8.04
 i  2  18  1  8.05
 i  2  19  1  8.07
 i  2  20  1  8.07
 i  2  21  1  8.05
 i  2  22  1  8.04
 i  2  23  1  8.02
 i  2  24  1  8.00
 i  2  25  1  8.00
 i  2  26  1  8.02
 i  2  27  1  8.04
 i  2  28  2  8.04
 i  2  30  2  8.02
 e
 /* envlpx.sco */

See Also		~

|envlpxr| envlpxr, |linen| linen, |linenr| linenr

Credits		~

Thanks goes to Luis Jure for pointing out a mistake with iatss.

------------------------------------------------------------------------------
*envlpxr*
envlpxr	~

envlpxr --  The envlpx opcode with a final release segment.

Description		~

envlpxr is the same as |envlpx| envlpx except that the final segment is
entered only on sensing a MIDI note release. The note is then extended by the
decay time.

Syntax		~

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

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

Initialization		~

irise -- rise time in seconds. A zero or negative value signifies no rise
modification.

idur -- overall duration in seconds. A zero or negative value will cause
initialization to be skipped.

idec -- decay time in seconds. Zero means no decay. An idec > idur will cause
a truncated decay.

ifn -- function table number of stored rise shape with extended guard point.

iatss -- attenuation factor, by which the last value of the envlpx rise is
modified during the note's pseudo steady state. A factor greater than 1
causes an exponential growth and a factor less than 1 creates an exponential
decay. A factor of 1 will maintain a true steady state at the last rise
value. Note that this attenuation is not by fixed rate (as in a piano), but
is sensitive to a note's duration. However, if iatss is negative (or if
steady state < 4 k-periods) a fixed attenuation rate of abs(iatss) per second
will be used. 0 is illegal.

iatdec -- attenuation factor by which the closing steady state value is
reduced exponentially over the decay period. This value must be positive and
is normally of the order of .01. A large or excessively small value is apt to
produce a cutoff which is audible. A zero or negative value is illegal.

ixmod (optional, between +- .9 or so) -- exponential curve modifier,
influencing the steepness of the exponential trajectory during the steady
state. Values less than zero will cause an accelerated growth or decay
towards the target (e.g. subito piano). Values greater than zero will cause a
retarded growth or decay. The default value is zero (unmodified exponential).

irind (optional) -- independence flag. If left zero, the release time (idec)
will influence the extended life of the current note following a note-off. If
non-zero, the idec time is quite independent of the note extension (see
below). The default value is 0.

Performance		~

kamp, xamp -- input amplitude signal.

envlpxr is an example of the special Csound "r" units that contain a note-off
sensor and release time extender. When each senses a score event termination
or a MIDI noteoff, it will immediately extend the performance time of the
current instrument by idec seconds unless it is made independent by irind.
Then it will begin a decay from wherever it was at the time.

These "r" units can also be modified by MIDI noteoff velocities (see
veloffs). If the irind flag is on (non-zero), the overall performance time is
unaffected by note-off and veloff data.

Multiple "r" units. When two or more "r" units occur in the same instrument
it is usual to have only one of them influence the overall note duration.
This is normally the master amplitude unit. Other units controlling, say,
filter motion can still be sensitive to note-off commands while not affecting
the duration by making them independent (irind non-zero). Depending on their
own idec (release time) values, independent "r" units may or may not reach
their final destinations before the instrument terminates. If they do, they
will simply hold their target values until termination. If two or more "r"
units are simultaneously master, note extension is by the greatest idec.

See Also		~

|envlpx| envlpx, |linen| linen, |linenr| linenr

Credits		~

Thanks goes to Luis Jure for pointing out a mistake with iatss.

------------------------------------------------------------------------------
*event*
event	~

event --  Generates a score event from an instrument.

Description		~

Generates a score event from an instrument.

Syntax		~

event "scorechar", kinsnum, kdelay, kdur, [, kp4] [, kp5] [, ...]

event "scorechar", "insname", kdelay, kdur, [, kp4] [, kp5] [, ...]

Initialization		~

"scorechar" -- A string (in double-quotes) representing the first p-field in
a score statement. This is usually |e| "e", |f| "f", or |i| "i".

"insname" -- A string (in double-quotes) representing a named instrument.

Performance		~

kinsnum -- The instrument to use for the event. This corresponds to the first
p-field, p1, in a score statement.

kdelay -- When (in seconds) the event will occur from the current performance
time. This corresponds to the second p-field, p2, in a score statement.

kdur -- How long (in seconds) the event will happen. This corresponds to the
third p-field, p3, in a score statement.

kp4, kp5, ... (optional) -- Parameters representing additional p-field in a
score statement. It starts with the fourth p-field, p4.

Examples		~

Here is an example of the event opcode. It uses the files event.orc and
event.sco.

Example 1. Example of the event opcode.

 /* event.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1 - an oscillator with a high note.
 instr 1
; Create a trigger and set its initial value to 1.
ktrigger init 1

; If the trigger is equal to 0, continue playing.
; If not, schedule another event.
if (ktrigger == 0) goto contin
  ; kscoreop="i", an i-statement.
  ; kinsnum=2, play Instrument #2.
  ; kwhen=1, start at 1 second.
  ; kdur=0.5, play for a half-second.
  event "i", 2, 1, 0.5

  ; Make sure the event isn't triggered again.
  ktrigger = 0

 contin:
a1 oscils 10000, 440, 1
out a1
 endin

 ; Instrument #2 - an oscillator with a low note.
 instr 2
a1 oscils 10000, 220, 1
out a1
 endin
 /* event.orc */

 /* event.sco */
 /* Written by Kevin Conder */
 ; Make sure the score plays for two seconds.
 f 0 2

 ; Play Instrument #1 for a half-second.
 i 1 0 0.5
 e
 /* event.sco */

Here is an example of the event opcode using a named instrument. It uses the
files event_named.orc and event_named.sco.

Example 2. Example of the event opcode using a named instrument.

 /* event_named.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1 - an oscillator with a high note.
 instr 1
; Create a trigger and set its initial value to 1.
ktrigger init 1

; If the trigger is equal to 0, continue playing.
; If not, schedule another event.
if (ktrigger == 0) goto contin
  ; kscoreop="i", an i-statement.
  ; kinsnum="low_note", instrument named "low_note".
  ; kwhen=1, start at 1 second.
  ; kdur=0.5, play for a half-second.
  event "i", "low_note", 1, 0.5

  ; Make sure the event isn't triggered again.
  ktrigger = 0

 contin:
a1 oscils 10000, 440, 1
out a1
 endin

 ; Instrument "low_note" - an oscillator with a low note.
 instr low_note
a1 oscils 10000, 220, 1
out a1
 endin
 /* event_named.orc */

 /* event_named.sco */
 /* Written by Kevin Conder */
 ; Make sure the score plays for two seconds.
 f 0 2

 ; Play Instrument #1 for a half-second.
 i 1 0 0.5
 e
 /* event_named.sco */

Credits		~

New in version 4.17

Thanks goes to Matt Ingalls for helping to fix the example.

Thanks goes to Matt Ingalls for helping clarify the kwhen/kdelay parameter.

------------------------------------------------------------------------------
*exp*
exp	~

exp --  Returns e raised to the x-th power.

Description		~

Returns e raised to the xth power.

Syntax		~

exp(x) (no rate restriction)

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

Examples		~

Here is an example of the exp opcode. It uses the files exp.orc and exp.sco.

Example 1. Example of the exp opcode.

 /* exp.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
i1 = exp(8)
print i1
 endin
 /* exp.orc */

 /* exp.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* exp.sco */

Its output should include a line like this:

 instr 1:  i1 = 2980.958

See Also		~

|abs| abs, |frac| frac, |int| int, |log| log, |log10| log10, |opi| i, |sqrt|
sqrt

------------------------------------------------------------------------------
*expon*
expon	~

expon --  Trace an exponential curve between specified points.

Description		~

Trace an exponential curve between specified points.

Syntax		~

ar expon ia, idur1, ib

kr expon ia, idur1, ib

Initialization		~

ia -- starting value. Zero is illegal for exponentials.

ib, ic, etc. -- value after dur1 seconds, etc. For exponentials, must be
non-zero and must agree in sign with ia.

idur1 -- duration in seconds of first segment. A zero or negative value will
cause all initialization to be skipped.

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.

Examples		~

Here is an example of the expon opcode. It uses the files expon.orc and
expon.sco.

Example 1. Example of the expon opcode.

 /* expon.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Define kcps as a frequency value that exponentially declines
; from 880 to 220. It declines over the period set by p3.
kcps expon 880, p3, 220

a1 oscil 20000, kcps, 1
out a1
 endin
 /* expon.orc */

 /* expon.sco */
 /* Written by Kevin Conder */
 ; Table #1, a sine wave.
 f 1 0 16384 10 1

 ; Play Instrument #1 for two seconds.
 i 1 0 2
 e
 /* expon.sco */

See Also		~

|expseg| expseg, |expsegr| expsegr, |line| line, |linseg| linseg, |linsegr|
linsegr

------------------------------------------------------------------------------
*exprand*
exprand	~

exprand --  Exponential distribution random number generator (positive values
only).

Description		~

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

Syntax		~

ar exprand krange

ir exprand krange

kr exprand krange

Performance		~

krange -- the range of the random numbers (0 - krange). Outputs only positive
numbers.

For more detailed explanation of these distributions, see:

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

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

Examples		~

Here is an example of the exprand opcode. It uses the files exprand.orc and
exprand.sco.

Example 1. Example of the exprand opcode.

 /* exprand.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Generate a random between 0 and 1.
; krange = 1

i1 exprand 1

print i1
 endin
 /* exprand.orc */

 /* exprand.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for one second.
 i 1 0 1
 e
 /* exprand.sco */

Its output should include a line like this:

 instr 1:  i1 = 0.174

See Also		~

|betarand| betarand, |bexprnd| bexprnd, |cauchy| cauchy, |gauss| gauss,
|linrand| linrand, |pcauchy| pcauchy, |poisson| poisson, |trirand| trirand,
|unirand| unirand, |weibull| weibull

Credits		~

Author: Paris Smaragdis 
MIT, Cambridge          
1995                    

------------------------------------------------------------------------------
*expseg*
expseg	~

expseg --  Trace a series of exponential segments between specified points.

Description		~

Trace a series of exponential segments between specified points.

Syntax		~

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

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

Initialization		~

ia -- starting value. Zero is illegal for exponentials.

ib, ic, etc. -- value after dur1 seconds, etc. For exponentials, must be
non-zero and must agree in sign with ia.

idur1 -- duration in seconds of first segment. A zero or negative value will
cause all initialization to be skipped.

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

Performance		~

These units generate control or audio signals whose values can pass through 2
or more specified points. The sum of dur values may or may not equal the
instrument's performance time: a shorter performance will truncate the
specified pattern, while a longer one will cause the last-defined segment to
continue on in the same direction.

Note that the |expseg| expseg opcode does not operate correctly at audio rate
when segments are shorter than a k-period. Try the |expsega| expsega opcode
instead.

Examples		~

Here is an example of the expseg opcode. It uses the files expseg.orc and
expseg.sco.

Example 1. Example of the expseg opcode.

 /* expseg.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; p4 = frequency in pitch-class notation.
kcps = cpspch(p4)

; Create an amplitude envelope.
kenv expseg 0.01, p3*0.25, 1, p3*0.75, 0.01
kamp = kenv * 30000

a1 oscil kamp, kcps, 1
out a1
 endin
 /* expseg.orc */

 /* expseg.sco */
 /* Written by Kevin Conder */
 ; Table #1, a sine wave.
 f 1 0 16384 10 1

 ; Play Instrument #1 for a half-second, p4=8.00
 i 1 0 0.5 8.00
 ; Play Instrument #1 for a half-second, p4=8.01
 i 1 1 0.5 8.01
 ; Play Instrument #1 for a half-second, p4=8.02
 i 1 2 0.5 8.02
 ; Play Instrument #1 for a half-second, p4=8.03
 i 1 3 0.5 8.03
 e
 /* expseg.sco */

See Also		~

|expon| expon, |expsega| expsega, |expsegr| expsegr, |line| line, |linseg|
linseg, |linsegr| linsegr

Credits		~

Author: Gabriel Maldonado

New in Csound 3.57

------------------------------------------------------------------------------
*expsega*
expsega	~

expsega --  An exponential segment generator operating at a-rate.

Description		~

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

Syntax		~

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

Initialization		~

ia -- starting value. Zero is illegal.

ib, ic, etc. -- value after idur1 seconds, etc. must be non-zero and must
agree in sign with ia.

idur1 -- duration in seconds of first segment. A zero or negative value will
cause all initialization to be skipped.

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

Performance		~

These units generate control or audio signals whose values can pass through
two or more specified points. The sum of dur values may or may not equal the
instrument's performance time. A shorter performance will truncate the
specified pattern, while a longer one will cause the last defined segment to
continue on in the same direction.

Examples		~

Here is an example of the expsega opcode. It uses the files expsega.orc and
expsega.sco.

Example 1. Example of the expsega opcode.

 /* expsega.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Define a short percussive amplitude envelope that
; goes from 0.01 to 20,000 and back.
aenv expsega 0.01, 0.1, 20000, 0.1, 0.01

a1 oscil aenv, 440, 1
out a1
 endin
 /* expsega.orc */

 /* expsega.sco */
 /* Written by Kevin Conder */
 ; Table #1, a sine wave.
 f 1 0 16384 10 1

 ; Play Instrument #1 for one second.
 i 1 0 1
 ; Play Instrument #1 for one second.
 i 1 1 1
 ; Play Instrument #1 for one second.
 i 1 2 1
 ; Play Instrument #1 for one second.
 i 1 3 1
 e
 /* expsega.sco */

See Also		~

|expseg| expseg, |expsegr| expsegr

Credits		~

Author: Gabriel Maldonado

New in Csound 3.57

------------------------------------------------------------------------------
*expsegr*
expsegr	~

expsegr --  Trace a series of exponential segments between specified points
including a release segment.

Description		~

Trace a series of exponential segments between specified points including a
release segment.

Syntax		~

ar expsegr ia, idur1, ib [, idur2] [, ic] [...], irel, iz

kr expsegr ia, idur1, ib [, idur2] [, ic] [...], irel, iz

Initialization		~

ia -- starting value. Zero is illegal for exponentials.

ib, ic, etc. -- value after dur1 seconds, etc. For exponentials, must be
non-zero and must agree in sign with ia.

idur1 -- duration in seconds of first segment. A zero or negative value will
cause all initialization to be skipped.

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

irel, iz -- duration in seconds and final value of a note releasing segment.

Performance		~

These units generate control or audio signals whose values can pass through 2
or more specified points. The sum of dur values may or may not equal the
instrument's performance time: a shorter performance will truncate the
specified pattern, while a longer one will cause the last-defined segment to
continue on in the same direction.

expsegr is amongst the Csound "r" units that contain a note-off sensor and
release time extender. When each senses an event termination or MIDI noteoff,
it immediately extends the performance time of the current instrument by irel
seconds, and sets out to reach the value iz by the end of that period (no
matter which segment the unit is in). "r" units can also be modified by MIDI
noteoff velocities. For two or more extenders in an instrument, extension is
by the greatest period.

Examples		~

Here is an example of the expsegr opcode. It uses the files expsegr.orc and
expsegr.sco.

Example 1. Example of the expsegr opcode.

 /* expsegr.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; p4 = frequency in pitch-class notation.
kcps = cpspch(p4)

; Use an amplitude envelope with second-long release.
kenv expsegr 0.01, p3/2, 1, p3/2, 0.01, 1, 1
kamp = kenv * 30000

a1 oscil kamp, kcps, 1
out a1
 endin
 /* expsegr.orc */

 /* expsegr.sco */
 /* Written by Kevin Conder */
 ; Table #1, a sine wave.
 f 1 0 16384 10 1

 ; Make sure the score lasts for four seconds.
 f 0 4

 ; p4 = frequency (in pitch-class notation).
 ; Play Instrument #1 for a half-second, p4=8.00
 i 1 0 0.5 8.00
 ; Play Instrument #1 for a half-second, p4=8.01
 i 1 1 0.5 8.01
 ; Play Instrument #1 for a half-second, p4=8.02
 i 1 2 0.5 8.02
 ; Play Instrument #1 for a half-second, p4=8.03
 i 1 3 0.5 8.03
 e
 /* expsegr.sco */

See Also		~

|expon| expon, |expseg| expseg, |expsega| expsega, |line| line, |linseg|
linseg, |linsegr| linsegr

Credits		~

Author: Barry L. Vercoe

New in Csound 3.47

------------------------------------------------------------------------------
*filelen*
filelen	~

filelen --  Returns the length of a sound file.

Description		~

Returns the length of a sound file.

Syntax		~

ir filelen ifilcod

Initialization		~

ifilcod -- sound file to be queried

Performance		~

filelen returns the length of the sound file ifilcod in seconds.

Examples		~

Here is an example of the filelen opcode. It uses the files filelen.orc,
filelen.sco, and mary.wav.

Example 1. Example of the filelen opcode.

 /* filelen.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Print out the length of the audio file
; "mary.wav" in seconds.
ilen  filelen "mary.wav"
print ilen
 endin
 /* filelen.orc */

 /* filelen.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for 1 second.
 i 1 0 1
 e
 /* filelen.sco */

The audio file "mary.wav" is 3.5 seconds long. So filelen's output should
include a line like this:

 instr 1:  ilen = 3.501

See Also		~

|filenchnls| filenchnls, |filepeak| filepeak, |filesr| filesr

Credits		~

Author: Matt Ingalls 
July 1999            

New in Csound version 3.57

------------------------------------------------------------------------------
*filenchnls*
filenchnls	~

filenchnls --  Returns the number of channels in a sound file.

Description		~

Returns the number of channels in a sound file.

Syntax		~

ir filenchnls ifilcod

Initialization		~

ifilcod -- sound file to be queried

Performance		~

filenchnls returns the number of channels in the sound file ifilcod.

Examples		~

Here is an example of the filenchnls opcode. It uses the files
filenchnls.orc, filenchnls.sco, and mary.wav.

Example 1. Example of the filenchnls opcode.

 /* filenchnls.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Print out the number of channels in the
; audio file "mary.wav".
ichnls filenchnls "mary.wav"
print ichnls
 endin
 /* filenchnls.orc */

 /* filenchnls.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for 1 second.
 i 1 0 1
 e
 /* filenchnls.sco */

The audio file "mary.wav" is monoaural (1 channel). So filenchnls's output
should include a line like this:

 instr 1:  ichnls = 1.000

See Also		~

|filelen| filelen, |filepeak| filepeak, |filesr| filesr

Credits		~

Author: Matt Ingalls 
July 1999            

New in Csound version 3.57

------------------------------------------------------------------------------
*filepeak*
filepeak	~

filepeak --  Returns the peak absolute value of a sound file.

Description		~

Returns the peak absolute value of a sound file.

Syntax		~

ir filepeak ifilcod [, ichnl]

Initialization		~

ifilcod -- sound file to be queried

ichnl (optional, default=0) -- channel to be used in calculating the peak
value. Default is 0.

  * ichnl = 0 returns peak value of all channels

  * ichnl > 0 returns peak value of ichnl

Performance		~

filepeak returns the peak absolute value of the sound file ifilcod.
Currently, filepeak supports only AIFF-C float files.

Examples		~

Here is an example of the filepeak opcode. It uses the files filepeak.orc,
filepeak.sco, and mary.wav.

Example 1. Example of the filepeak opcode.

 /* filepeak.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Print out the peak absolute value of the
; audio file "mary.wav".
ipeak filepeak "mary.wav"
print ipeak
 endin
 /* filepeak.orc */

 /* filepeak.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for 1 second.
 i 1 0 1
 e
 /* filepeak.sco */

The peak absolute value of the audio file "mary.wav" is 0.306902. So
filepeak's output should include a line like this:

 instr 1:  ipeak = 0.307

See Also		~

|filelen| filelen, |filenchnls| filenchnls, |filesr| filesr

Credits		~

Author: Matt Ingalls 
July 1999            

New in Csound version 3.57

------------------------------------------------------------------------------
*filesr*
filesr	~

filesr --  Returns the sample rate of a sound file.

Description		~

Returns the sample rate of a sound file.

Syntax		~

ir filesr ifilcod

Initialization		~

ifilcod -- sound file to be queried

Performance		~

filesr returns the sample rate of the sound file ifilcod.

Examples		~

Here is an example of the filesr opcode. It uses the files filesr.orc,
filesr.sco, and mary.wav.

Example 1. Example of the filesr opcode.

 /* filesr.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Print out the sampling rate of the
; audio file "mary.wav".
isr filesr "mary.wav"
print isr
 endin
 /* filesr.orc */

 /* filesr.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for 1 second.
 i 1 0 1
 e
 /* filesr.sco */

The audio file "mary.wav" was sampled at 44.1 KHz. So filesr's output should
include a line like this:

 instr 1:  isr = 44100.000

See Also		~

|filelen| filelen, |filenchnls| filenchnls, |filepeak| filepeak

Credits		~

Author: Matt Ingalls 
July 1999            

New in Csound version 3.57

------------------------------------------------------------------------------
*filter2*
filter2	~

filter2 --  Performs filtering using a transposed form-II digital filter
lattice with no time-varying control.

Description		~

General purpose custom filter with time-varying pole control. The filter
coefficients implement the following difference equation:

(1)*y(n) = b0*x[n] + b1*x[n-1] +...+ bM*x[n-M] - a1*y[n-1] -...- aN*y[n-N]

the system function for which is represented by:

           B(Z)      b0 + b1*Z-1  + ... + bM*Z-M
  H(Z)  =  ----  =  --------------------------
           A(Z)       1 + a1*Z-1  + ... + aN*Z-N

Syntax		~

ar filter2 asig, iM, iN, ib0, ib1, ..., ibM, ia1, ia2, ..., iaN

kr filter2 ksig, iM, iN, ib0, ib1, ..., ibM, ia1, ia2, ..., iaN

Initialization		~

At initialization the number of zeros and poles of the filter are specified
along with the corresponding zero and pole coefficients. The coefficients
must be obtained by an external filter-design application such as Matlab and
specified directly or loaded into a table via |gen01| GEN01.

Performance		~

The filter2 opcodes perform filtering using a transposed form-II digital
filter lattice with no time-varying control.

Since filter2 implements generalized recursive filters, it can be used to
specify a large range of general DSP algorithms. For example, a digital
waveguide can be implemented for musical instrument modeling using a pair of
|delayr| delayr and |delayw| delayw opcodes in conjunction with the filter2
opcode.

Examples		~

A first-order linear-phase lowpass linear-phase FIR filter operating on a
k-rate signal:

 k1 filter2 ksig, 2, 0, 0.5, 0.5   ;; k-rate FIR filter

See Also		~

|zfilter2| zfilter2

Credits		~

Author: Michael A. Casey 
M.I.T.                   
Cambridge, Mass.         
1997                     

------------------------------------------------------------------------------
*fin*
fin	~

fin --  Read signals from a file at a-rate.

Description		~

Read signals from a file at a-rate.

Syntax		~

fin ifilename, iskipframes, iformat, ain1 [, ain2] [, ain3] [,...]

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.

  * 0 - 32 bit floating points without header

  * 1 - 16 bit integers without header

Performance		~

fin (file input) is the complement of |fout| fout: it reads a multichannel
file to generate audio rate signals. At the present time no header is
supported for the file format. The user must be sure that the number of
channels of the input file is the same as the number of ainX arguments.

See Also		~

|fini| fini, |fink| fink

Credits		~

Author: Gabriel Maldonado 
Italy                     
1999                      

New in Csound version 3.56

------------------------------------------------------------------------------
*fini*
fini	~

fini --  Read signals from a file at i-rate.

Description		~

Read signals from a file at i-rate.

Syntax		~

fini ifilename, iskipframes, iformat, in1 [, in2] [, in3] [, ...]

Initialization		~

ifilename -- input file name (can be a string or a handle number generated by
|fiopen| 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.

  * 0 - floating points in text format (loop; see below)

  * 1 - floating points in text format (no loop; see below)

  * 2 - 32 bit floating points in binary format (no loop)

Performance		~

fini is the complement of |fouti| fouti and |foutir| foutir. It reads the
values each time the corresponding instrument note is activated. When iformat
is set to 0 and the end of file is reached, the file pointer is zeroed. This
restarts the scan from the beginning. When iformat is set to 1 or 2, no
looping is enabled and at the end of file the corresponding variables will be
filled with zeroes.

See Also		~

|fin| fin, |fink| fink

Credits		~

Author: Gabriel Maldonado 
Italy                     
1999                      

New in Csound version 3.56

------------------------------------------------------------------------------
*fink*
fink	~

fink --  Read signals from a file at k-rate.

Description		~

Read signals from a file at k-rate.

Syntax		~

fink ifilename, iskipframes, iformat, kin1 [, kin2] [, kin3] [,...]

Initialization		~

ifilename -- input file name (can be a string or a handle number generated by
fiopen)

iskipframes -- number of frames to skip at the start (every frame contains a
sample of each channel)

iformat -- a number specifying the input file format.

  * 0 - 32 bit floating points without header

  * 1 - 16 bit integers without header

Performance		~

fink is the same as |fin| fin but operates at k-rate.

See Also		~

|fin| fin, |fini| fini

Credits		~

Author: Gabriel Maldonado 
Italy                     
1999                      

New in Csound version 3.56

------------------------------------------------------------------------------
*fiopen*
fiopen	~

fiopen --  Opens a file in a specific mode.

Description		~

fiopen can be used to open a file in one of the specified modes.

Syntax		~

ihandle fiopen ifilename, imode

Initialization		~

ihandle -- a number which specifies this file.

ifilename -- the output file's name (in double-quotes).

imode -- choose the mode of opening the file. imode can be a value chosen
among the following:

  * 0 - open a text file for writing

  * 1 - open a text file for reading

  * 2 - open a binary file for writing

  * 3 - open a binary file for reading

Performance		~

fiopen opens a file to be used by the |fout| fout family of opcodes. It must
be defined in the header section, external to any instruments. It returns a
number, ihandle, which unequivocally refers to the opened file.

Notice that |fout| fout and |foutk| foutk can use either a string containing
a file pathname, or a handle-number generated by fiopen. Whereas, with
|fouti| fouti and |foutir| foutir, the target file can be only specified by
means of a handle-number.

See Also		~

|fout| fout, |fouti| fouti, |foutir| foutir, |foutk| foutk

Credits		~

Author: Gabriel Maldonado 
Italy                     
1999                      

New in Csound version 3.56

------------------------------------------------------------------------------
*flanger*
flanger	~

flanger --  A user controlled flanger.

Description		~

A user controlled flanger.

Syntax		~

ar flanger asig, adel, kfeedback [, imaxd]

Initialization		~

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

Performance		~

asig -- input signal

adel -- delay in seconds

kfeedback -- feedback amount (in normal tasks this should not exceed 1, even
if bigger values are allowed)

This unit is useful for generating choruses and flangers. The delay must be
varied at a-rate 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.
This unit is very similar to |wguide1| wguide1, the only difference is
flanger does not have the lowpass filter.

Examples		~

Here is an example of the flanger opcode. It uses the files flanger.orc,
flanger.sco, and beats.wav.

Example 1. Example of the flanger opcode.

 /* flanger.orc */
 /* Written by Kevin Conder */
 ; Initialize the global variables.
 sr = 44100
 kr = 4410
 ksmps = 10
 nchnls = 1

 ; Instrument #1.
 instr 1
; Use the "beat.wav" audio file.
asig soundin "beats.wav"

; Vary the delay amount from 0 to 0.01 seconds.
adel line 0, p3, 0.01
kfeedback = 0.7

; Apply flange to the input signal.
aflang flanger asig, adel, kfeedback

; It can get loud, so clip its amplitude to 30,000.
a1 clip aflang, 1, 30000
out a1
 endin
 /* flanger.orc */

 /* flanger.sco */
 /* Written by Kevin Conder */
 ; Play Instrument #1 for two seconds.
 i 1 0 2
 e
 /* flanger.sco */

Credits		~

Author: Gabriel Maldonado 
Italy                     

New in Csound version 3.49

------------------------------------------------------------------------------
*flashtxt*
flashtxt	~

flashtxt --  Allows text to be displayed from instruments like sliders

Description		~

Allows text to be displayed from instruments like sliders etc. (only on Unix
and Windows at present)

Syntax		~

flashtxt iwhich, String

Initialization		~

iwhich -- the number of the window.

String -- the string to be displayed.

Performance		~

A window is created, identified by the iwhich argument, with the text string
displayed. If the text is replaced by a number then the window id deleted.
Note that the text windows are globally numbered so different instruments can
change the text, and the window survives the instance of the instrument.

Examples		~

Here is an example of the flashtxt opcode. It uses the files flashtxt.orc and
flashtxt.sco.

Example 1. Example of the flashtxt opcode.

 /* flashtxt.orc */
 ; Initialize the global variables.
 sr = 44100
 kr = 44100
 ksmps = 1
 nchnls = 1

 instr 1
flashtxt 1, "Instr 1 live"
ao oscil 4000, 440, 1
out ao
 endin
 /* flashtxt.orc */

 /* flashtxt.sco */
 ; Table 1: an ordinary sine wave.
 f 1 0 32768 10 1

 ; Play Instrument #1 for three seconds.
 i 1 0 3
 e
 /* flashtxt.sco */

------------------------------------------------------------------------------
*flbox*
FLbox	~

FLbox --  A FLTK widget that displays text inside of a box.

Description		~

A FLTK widget that displays text inside of a box.

Syntax		~

ihandle FLbox "label", itype, ifont, isize, iwidth, iheight, ix, iy [, image]

Initialization		~

ihandle -- a handle value (an integer number) that unequivocally references a
corresponding widget. This is used by other opcodes that modify a widget's
properties (see |controlfltkappearance| Modifying FLTK Widget Appearance). It
is automatically output by FLbox and must not be set by the user label. (The
user label is a double-quoted string containing some user-provided text
placed near the widget.)

"label" -- a double-quoted string containing some user-provided text, placed
near corresponding widget.

Notice that with FLbox, it is not necessary to call the |flsettexttype|
FLsetTextType opcode at all in order to use a symbol. In this case, it is
sufficient to set a label starting with "@" followed by the proper formatting
string.

The following symbols are supported:

FLTK label supported symbols.

The @ sign may be followed by the following optional "formatting" characters,
in this order:

 1. "#" forces square scaling rather than distortion to the widget's shape.

 2. +[1-9] or -[1-9] tweaks the scaling a little bigger or smaller.

 3. [1-9] rotates by a multiple of 45 degrees. "6" does nothing, the others
    point in the direction of that key on a numeric keypad.

itype -- an integer number denoting the appearance of the widget.

The following values are legal for itype:

  * 1 - flat box

  * 2 - up box

  * 3 - down box

  * 4 - thin up box

  * 5 - thin down box

  * 6 - engraved box

  * 7 - embossed box

  * 8 - border box

  * 9 - shadow box

  * 10 - rounded box

  * 11 - rounded box with shadow

  * 12 - rounded flat box

  * 13 - rounded up box

  * 14 - rounded down box

  * 15 - diamond up box

  * 16 - diamond down box

  * 17 - oval box

  * 18 - oval shadow box

  * 19 - oval flat box

ifont -- an integer number denoting the font of FLbox.

ifont argument to set the font type. The following values are legal for
ifont:

  * 1 - helvetica (same as "Arial" under Windows)

  * 2 - helvetica bold

  * 3 - helvetica italic

  * 4 - helvetica bold italic

  * 5 - courier

  * 6 - courier bold

  * 7 - courier italic

  * 8 - courier bold italic

  * 9 - times

  * 10 - times bold

  * 11 - times italic

  * 12 - times bold italic

  * 13 - symbol

  * 14 - screen

  * 15 - screen bold

  * 16 - dingbats

isize -- size of the font.

iwidth -- width of widget.

iheight -- height of widget.

ix -- horizontal position of the upper left corner of the valuator, relative
to the upper left corner of corresponding window. (Expressed in pixels.)

iy -- vertical position of the upper left corner of the valuator, relative to
the upper left corner of corresponding window. (Expressed in pixels.)

image -- a handle referring to an eventual image opened with bmopen opcode.
If it is set, it allows a skin for that widget.

  Note about the bmopen opcode                                                
  Although the documentation mentions the bmopen opcode, it has not been      
  implemented in Csound 4.22.                                                 

Performance		~

FLbox is useful to show some text in a window. The text is bounded by a box,
whose aspect depends on itype argument.

Note that FLbox is not a valuator and its value is fixed. Its value cannot be
modified.

See Also		~

|flbutbank| FLbutBank, |flbutton| FLbutton, |flprintk| FLprintk, |flprintk2|
FLprintk2, |flvalue| FLvalue

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flbutbank*
FLbutBank	~

FLbutBank --  A FLTK widget opcode that creates a bank of buttons.

Description		~

A FLTK widget opcode that creates a bank of buttons.

Syntax		~

kout, ihandle FLbutBank itype, inumx, inumy, iwidth, iheight, ix, iy, iopcode
[, kp1] [, kp2] [, kp3] [, kp4] [, kp5] [....] [, kpN]

Initialization		~

ihandle -- a handle value (an integer number) that unequivocally references a
corresponding widget. This is used by other opcodes that modify a widget's
properties (see |controlfltkappearance| Modifying FLTK Widget Appearance). It
is automatically output by FLbutBank and must not be set by the user label.
(The user label is a double-quoted string containing some user-provided text
placed near the widget.)

itype -- an integer number denoting the appearance of the widget. Its meaning
is different for different types of widget.

inumx -- number of buttons in each row of the bank.

inumy -- number of buttons in each column of the bank

ix -- horizontal position of upper left corner of the valuator, relative to
the upper left corner of corresponding window, expressed in pixels

iy -- vertical position of upper left corner of the valuator, relative to the
upper left corner of corresponding window, expressed in pixels

iopcode -- score opcode type. You have to provide the ascii code of the
letter corresponding to the score opcode. At present time only "i" (ascii
code 105) score statements are supported. A zero value refers to a default
value of "i". So both 0 and 105 activates the |i| i opcode. A value of -1
disables this opcode feature.

Performance		~

kout -- output value

kp1, kp2, ..., kpN -- arguments of the activated instruments.

The FLbutBank opcode creates a bank of buttons. For example, the following
line:

 gkButton,ihb1  FLbutBank  12, 8, 8, 380, 180, 50, 350, 0, 7, 0, 0, 5000, 6000

will create the this bank:

FLbutBank.

A click to a button checks that button. It may also uncheck a previous
checked button belonging to the same bank. So the behaviour is always that of
radio-buttons. Notice that each button is labeled with a progressive number.
The kout argument is filled with that number when corresponding button is
checked.

FLbutBank not only outputs a value but can also activate (or schedule) an
instrument provided by the user each time a button is pressed. If the iopcode
argument is set to a negative number, no instrument is activated so this
feature is optional. In order to activate an instrument, iopcode must be set
to 0 or to 105 (the ascii code of character "i", referring to the |i| i score
opcode). P-fields of the activated instrument are kp1 (instrument number),
kp2 (action time), kp3 (duration) and so on with user p-fields.

The itype argument sets the type of buttons identically to the |flbutton|
FLbutton opcode. By adding 10 to the itype argument (i.e. by setting 11 for
type 1, 12 for type 2, 13 for type 3 and 14 for type 4), it is possible to
skip the current FLbutBank value when getting/setting snapshots (see
|controlfltkgeneral| General FLTK Widget-related Opcodes).

FLbutBank is very useful to retrieve snapshots.

See Also		~

|flbox| FLbox, |flbutton| FLbutton, |flprintk| FLprintk, |flprintk2|
FLprintk2, |flvalue| FLvalue

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flbutton*
FLbutton	~

FLbutton --  A FLTK widget opcode that creates a button.

Description		~

A FLTK widget opcode that creates a button.

Syntax		~

kout, ihandle FLbutton "label", ion, ioff, itype, iwidth, iheight, ix, iy,
iopcode [, kp1] [, kp2] [, kp3] [, kp4] [, kp5] [....] [, kpN]

Initialization		~

ihandle -- a handle value (an integer number) that unequivocally references a
corresponding widget. This is used by other opcodes that modify a widget's
properties (see |controlfltkappearance| Modifying FLTK Widget Appearance). It
is automatically output by FLbutton and must not be set by the user label.
(The user label is a double-quoted string containing some user-provided text
placed near the widget.)

"label" -- a double-quoted string containing some user-provided text, placed
near the corresponding widget.

Notice that with FLbutton, it is not necessary to call the |flsettexttype|
FLsetTextType opcode at all in order to use a symbol. In this case, it is
sufficient to set a label starting with "@" followed by the proper formatting
string.

The following symbols are supported:

FLTK label supported symbols.

The @ sign may be followed by the following optional "formatting" characters,
in this order:

 1. "#" forces square scaling rather than distortion to the widget's shape.

 2. +[1-9] or -[1-9] tweaks the scaling a little bigger or smaller.

 3. [1-9] rotates by a multiple of 45 degrees. "6" does nothing, the others
    point in the direction of that key on a numeric keypad.

ion -- value output when the button is checked.

ioff -- value output when the button is unchecked.

itype -- an integer number denoting the appearance of the widget.

Several kind of buttons are possible, according to the value of itype
argument:

  * 1 - normal button

  * 2 - light button

  * 3 - check button

  * 4 - round button

This is the appearance of the buttons:

FLbutton.

iwidth -- width of widget.

iheight -- height of widget.

ix -- horizontal position of upper left corner of the valuator, relative to
the upper left corner of corresponding window (expressed in pixels).

iy -- vertical position of upper left corner of the valuator, relative to the
upper left corner of corresponding window (expressed in pixels).

iopcode -- score opcode type. You have to provide the ascii code of the
letter corresponding to the score opcode. At present time only "i" (ascii
code 105) score statements are supported. A zero value refers to a default
value of "i". So both 0 and 105 activates the |i| i opcode. A value of -1
disables this opcode feature.

Performance		~

kout -- output value

kp1, kp2, ..., kpN -- arguments of the activated instruments.

Buttons of type 2, 3, and 4 also output (kout argument) the value contained
in the ion argument when checked, and that contained in ioff argument when
unchecked.

By adding 10 to itype argument (i.e. by setting 11 for type 1, 12 for type 2,
13 for type 3 and 14 for type 4) it is possible to skip the button value when
getting/setting snapshots (see later section). FLbutton not only outputs a
value, but can also activate (or schedule) an instrument provided by the user
each time a button is pressed.

If the iopcode argument is set to a negative number, no instrument is
activated. So this feature is optional. In order to activate an instrument,
iopcode must be set to 0 or to 105 (the ascii code of character "i",
referring to the |i| i score opcode).

P-fields of the activated instrument are kp1 (instrument number), kp2 (action
time), kp3 (duration) and so on with user p-fields. Notice that in dual state
buttons (light button, check button and round button), the instrument is
activated only when button state changes from unchecked to checked (not when
passing from checked to unchecked).

See Also		~

|flbox| FLbox, |flbutbank| FLbutBank, |flprintk| FLprintk, |flprintk2|
FLprintk2, |flvalue| FLvalue

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flcolor*
FLcolor	~

FLcolor --  A FLTK opcode that sets the primary colors.

Description		~

Sets the primary colors to RGB values given by the user.

Syntax		~

FLcolor ired, igreen, iblue

Initialization		~

ired -- The red color of the target widget. The range for each RGB component
is 0-255

igreen -- The green color of the target widget. The range for each RGB
component is 0-255

iblue -- The blue color of the target widget. The range for each RGB
component is 0-255

Performance		~

These opcodes modify the appearance of other widgets. There are two types of
such opcodes, those that don't contain the ihandle argument which affect all
subsequently declared widgets, and those without ihandle which affect only a
target widget previously defined.

FLcolor sets the primary colors to RGB values given by the user. This opcode
affects the primary color of (almost) all widgets defined next its location.
User can put several instances of FLcolor in front of each widget he intend
to modify. However, to modify a single widget, it would be better to use the
opcode belonging to the second type (i.e. those containing ihandle argument).

FLcolor is designed to modify the colors of a group of related widgets that
assume the same color. The influence of FLcolor on subsequent widgets can be
turned off by using -1 as the only argument of the opcode. Also, using -2 (or
-3) as the only value of FLcolor makes all next widget colors randomly
selected. The difference is that -2 selects a light random color, while -3
selects a dark random color.

See Also		~

|flcolor2| FLcolor2, |flhide| FLhide, |fllabel| FLlabel, |flsetalign|
FLsetAlign, |flsetbox| FLsetBox, |flsetcolor| FLsetColor, |flsetcolor2|
FLsetColor2, |flsetfont| FLsetFont, |flsetposition| FLsetPosition,
|flsetsize| FLsetSize, |flsettext| FLsetText, |flsettextcolor|
FLsetTextColor, |flsettextsize| FLsetTextSize, |flsettexttype| FLsetTextType,
|flsetvali| FLsetVal_i, |flsetval| FLsetVal, |flshow| FLshow

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flcolor2*
FLcolor2	~

FLcolor2 --  A FLTK opcode that sets the secondary (selection) color.

Description		~

FLcolor2 is the same of |flcolor| FLcolor except it affects the secondary
(selection) color.

Syntax		~

FLcolor2 ired, igreen, iblue

Initialization		~

ired -- The red color of the target widget. The range for each RGB component
is 0-255

igreen -- The green color of the target widget. The range for each RGB
component is 0-255

iblue -- The blue color of the target widget. The range for each RGB
component is 0-255

Performance		~

These opcodes modify the appearance of other widgets. There are two types of
such opcodes: those that don't contain the ihandle argument which affect all
subsequently declared widgets, and those without ihandle which affect only a
target widget previously defined.

FLcolor2 is the same of FLcolor except it affects the secondary (selection)
color. Setting it to -1 turns off the influence of FLcolor2 on subsequent
widgets. A value of -2 (or -3) makes all next widget secondary colors
randomly selected. The difference is that -2 selects a light random color,
while -3 selects a dark random color.

See Also		~

|flcolor| FLcolor, |flhide| FLhide, |fllabel| FLlabel, |flsetalign|
FLsetAlign, |flsetbox| FLsetBox, |flsetcolor| FLsetColor, |flsetcolor2|
FLsetColor2, |flsetfont| FLsetFont, |flsetposition| FLsetPosition,
|flsetsize| FLsetSize, |flsettext| FLsetText, |flsettextcolor|
FLsetTextColor, |flsettextsize| FLsetTextSize, |flsettexttype| FLsetTextType,
|flsetvali| FLsetVal_i, |flsetval| FLsetVal, |flshow| FLshow

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flcount*
FLcount	~

FLcount --  A FLTK widget opcode that creates a counter.

Description		~

Allows the user to increase/decrease a value with mouse clicks on a
corresponding arrow button.

Syntax		~

kout, ihandle FLcount "label", imin, imax, istep1, istep2, itype, iwidth,
iheight, ix, iy, iopcode [, kp1] [, kp2] [, kp3] [...] [, kpN]

Initialization		~

ihandle -- a handle value (an integer number) that unequivocally references a
corresponding widget. Used by further opcodes that changes some valuator's
properties. It is automatically set by the corresponding valuator.

"label" -- a double-quoted string containing some user-provided text, placed
near the corresponding widget.

imin -- minimum value of output range

imax -- maximum value of output range

istep1 -- a floating-point number indicating the increment of valuator value
corresponding to of each mouse click. istep1 is for coarse adjustments.

istep2 -- a floating-point number indicating the increment of valuator value
corresponding to of each mouse click. istep2 is for fine adjustments.

itype -- an integer number denoting the appearance of the valuator.

iwidth -- width of widget.

iheight -- height of widget.

ix -- horizontal position of upper left corner of the valuator, relative to
the upper left corner of corresponding window (expressed in pixels).

iy -- vertical position of upper left corner of the valuator, relative to the
upper left corner of corresponding window (expressed in pixels).

iopcode -- score opcode type. You have to provide the ascii code of the
letter corresponding to the score opcode. At present time only "i" (ascii
code 105) score statements are supported. A zero value refers to a default
value of "i". So both 0 and 105 activates the |i| i opcode. A value of -1
disables this opcode feature.

Performance		~

kout -- output value

kp1, kp2, ..., kpN -- arguments of the activated instruments.

FLcount allows the user to increase/decrease a value with mouse clicks on
corresponding arrow buttons:

FLcount.

There are two kind of arrow buttons, for larger and smaller steps. Notice
that FLcount not only outputs a value and a handle, but can also activate
(schedule) an instrument provided by the user each time a button is pressed.
P-fields of the activated instrument are kp1 (instrument number), kp2 (action
time), kp3 (duration) and so on with user p-fields. If the iopcode argument
is set to a negative number, no instrument is activated. So this feature is
optional.

See Also		~

|fljoy| FLjoy, |flkeyb| FLkeyb, |flknob| FLknob, |flroller| FLroller,
|flslider| FLslider, |fltext| FLtext

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flgetsnap*
FLgetsnap	~

FLgetsnap --  Retrieves a previously stored FLTK snapshot.

Description		~

Retrieves a previously stored snapshot (in memory), i.e. sets all valuator to
the corresponding values stored in that snaphot.

Syntax		~

inumsnap FLgetsnap index

Initialization		~

inumsnap -- current number of snapshots.

index -- a number referring unequivocally to a snapshot. Several snapshots
can be stored in the same bank.

Performance		~

FLgetsnap retrieves a previously stored snapshot (in memory), i.e. sets all
valuator to the corresponding values stored in that snapshot. The index
argument unequivocally must refer to an already existing snapshot. If the
index argument refers to an empty snapshot or to a snapshot that doesn't
exist, no action is done. FLsetsnap outputs the current number of snapshots
(inumsnap argument).

See Also		~

|flloadsnap| FLloadsnap, |flrun| FLrun, |flsavesnap| FLsavesnap, |flsetsnap|
FLsetsnap, |flupdate| FLupdate

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flgroup*
FLgroup	~

FLgroup --  A FLTK container opcode that groups child widgets.

Description		~

A FLTK container opcode that groups child widgets.

Syntax		~

FLgroup "label", iwidth, iheight, ix, iy [, iborder] [, image]

Initialization		~

"label" -- a double-quoted string containing some user-provided text, placed
near the corresponding widget.

iwidth -- width of widget.

iheight -- height of widget.

ix -- horizontal position of upper left corner of the valuator, relative to
the upper left corner of corresponding window (expressed in pixels).

iy -- vertical position of upper left corner of the valuator, relative to the
upper left corner of corresponding window (expressed in pixels).

iborder (optional, default=0) -- border type of the container. It is
expressed by means of an integer number chosen from the following:

  * 0 - no border

  * 1 - down box border

  * 2 - up box border

  * 3 - engraved border

  * 4 - embossed border

  * 5 - black line border

  * 6 - thin down border

  * 7 - thin up border

If the integer number doesn't match any of the previous values, no border is
provided as the default.

image (optional) -- a handle referring to an eventual image opened with the
bmopen opcode. If it is set, it allows a skin for that widget.

  Note about the bmopen opcode                                                
  Although the documentation mentions the bmopen opcode, it has not been      
  implemented in Csound 4.22.                                                 

Performance		~

Containers are useful to format the graphic appearance of the widgets. The
most important container is |flpanel| FLpanel, that actually creates a
window. It can be filled with other containers and/or valuators or other
kinds of widgets.

There are no k-rate arguments in containers.

See Also		~

|flgroupend| FLgroupEnd, |flpack| FLpack, |flpackend| FLpackEnd, |flpanel|
FLpanel, |flpanelend| FLpanelEnd, |flscroll| FLscroll, |flscrollend|
FLscrollEnd, |fltabs| FLtabs, |fltabsend| FLtabsEnd

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flgroupend*
FLgroupEnd	~

FLgroupEnd --  Marks the end of a group of FLTK child widgets.

Description		~

Marks the end of a group of FLTK child widgets.

Syntax		~

FLgroupEnd

Performance		~

Containers are useful to format the graphic appearance of the widgets. The
most important container is |flpanel| FLpanel, that actually creates a
window. It can be filled with other containers and/or valuators or other
kinds of widgets.

There are no k-rate arguments in containers.

See Also		~

|flgroup| FLgroup, |flpack| FLpack, |flpackend| FLpackEnd, |flpanel| FLpanel,
|flpanelend| FLpanelEnd, |flscroll| FLscroll, |flscrollend| FLscrollEnd,
|fltabs| FLtabs, |fltabsend| FLtabsEnd

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flhide*
FLhide	~

FLhide --  Hides the target FLTK widget.

Description		~

Hides the target FLTK widget, making it invisible.

Syntax		~

FLhide ihandle

Initialization		~

ihandle -- a handle value (an integer number) that unequivocally references a
corresponding widget. This is used by other opcodes that modify a widget's
properties (see |controlfltkappearance| Modifying FLTK Widget Appearance). It
is automatically output by FLbutBank and must not be set by the user label.
(The user label is a double-quoted string containing some user-provided text
placed near the widget.)

Performance		~

FLhide hides target widget, making it invisible.

See Also		~

|flcolor| FLcolor, |flcolor2| FLcolor2, |fllabel| FLlabel, |flsetalign|
FLsetAlign, |flsetbox| FLsetBox, |flsetcolor| FLsetColor, |flsetcolor2|
FLsetColor2, |flsetfont| FLsetFont, |flsetposition| FLsetPosition,
|flsetsize| FLsetSize, |flsettext| FLsetText, |flsettextcolor|
FLsetTextColor, |flsettextsize| FLsetTextSize, |flsettexttype| FLsetTextType,
|flsetvali| FLsetVal_i, |flsetval| FLsetVal, |flshow| FLshow

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*fljoy*
FLjoy	~

FLjoy --  A FLTK opcode that acts like a joystick.

Description		~

FLjoy is a squared area that allows the user to modify two output values at
the same time. It acts like a joystick.

Syntax		~

koutx, kouty, ihandlex, ihandley FLjoy "label", iminx, imaxx, iminy, imaxy,
iexpx, iexpy, idispx, idispy, iwidth, iheight, ix, iy

Initialization		~

ihandlex -- a handle value (an integer number) that unequivocally references
a corresponding widget. Used by further opcodes that changes some valuator's
properties. It is automatically set by the corresponding valuator.

ihandley -- a handle value (an integer number) that unequivocally references
a corresponding widget. Used by further opcodes that changes some valuator's
properties. It is automatically set by the corresponding valuator.

"label" -- a double-quoted string containing some user-provided text, placed
near the corresponding widget.

iminx -- minimum x value of output range

imaxx -- maximum x value of output range

iminy -- minimum y value of output range

imaxy -- maximum y value of output range

iwidth -- width of widget.

idispx -- a handle value that was output from a previous instance of the
|flvalue| FLvalue opcode to display the current value of the current valuator
in the FLvalue widget itself. If the user doesn't want to use this feature
that displays current values, it must be set to a negative number by the
user.

idispy -- a handle value that was output from a previous instance of the
|flvalue| FLvalue opcode to display the current value of the current valuator
in the FLvalue widget itself. If the user doesn't want to use this feature
that displays current values, it must be set to a negative number by the
user.

iexpx -- an integer number denoting the behaviour of valuator:

  * 0 = valuator output is linear

  * -1 = valuator output is exponential

All other positive numbers for iexpx indicate the number of an existing table
that is used for indexing. Linear interpolation is provided in table
indexing. A negative table number suppresses interpolation.

iexpy -- an integer number denoting the behaviour of valuator:

  * 0 = valuator output is linear

  * -1 = valuator output is exponential

All other positive numbers for iexpy indicate the number of an existing table
that is used for indexing. Linear interpolation is provided in table
indexing. A negative table number suppresses interpolation.

  IMPORTANT!                                                                  
  Notice that the tables used by valuators must be created with the |ftgen|   
  ftgen opcode and placed in the orchestra before the corresponding valuator. 
  They can not placed in the score. In fact, tables placed in the score are   
  created later than the initialization of the opcodes placed in the header   
  section of the orchestra.                                                   

iheight -- height of widget.

ix -- horizontal position of upper left corner of the valuator, relative to
the upper left corner of corresponding window (expressed in pixels).

iy -- vertical position of upper left corner of the valuator, relative to the
upper left corner of corresponding window (expressed in pixels).

Performance		~

koutx -- x output value

kouty -- y output value

See Also		~

|flcount| FLcount, |flkeyb| FLkeyb, |flknob| FLknob, |flroller| FLroller,
|flslider| FLslider, |fltext| FLtext

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flkeyb*
FLkeyb	~

FLkeyb --  Experimental, no documentation exists. May be deprecated in future
versions.

Description		~

Experimental, no documentation exists. May be deprecated in future versions.

Syntax		~

kout FLkeyb kparam1 [, kparam2] ... [, kparamN]

See Also		~

|flcount| FLcount, |fljoy| FLjoy, |flknob| FLknob, |flroller| FLroller,
|flslider| FLslider, |fltext| FLtext

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flknob*
FLknob	~

FLknob --  A FLTK widget opcode that creates a knob.

Description		~

A FLTK widget opcode that creates a knob.

Syntax		~

kout, ihandle FLknob "label", imin, imax, iexp, itype, idisp, iwidth, ix, iy
[, icursorsize]

Initialization		~

ihandle -- a handle value (an integer number) that unequivocally references a
corresponding widget. This is used by other opcodes that modify a widget's
properties (see |controlfltkappearance| Modifying FLTK Widget Appearance). It
is automatically output by FLknob and must not be set by the user label. (The
user label is a double-quoted string containing some user-provided text
placed near the widget.)

"label" -- a double-quoted string containing some user-provided text, placed
near the corresponding widget.

imin -- minimum value of output range.

imax -- maximum value of output range.

iexp -- an integer number denoting the behaviour of valuator:

  * 0 = valuator output is linear

  * -1 = valuator output is exponential

All other positive numbers for iexp indicate the number of an existing table
that is used for indexing. Linear interpolation is provided in table
indexing. A negative table number suppresses interpolation.

  IMPORTANT!                                                                  
  Notice that the tables used by valuators must be created with the |ftgen|   
  ftgen opcode and placed in the orchestra before the corresponding valuator. 
  They can not placed in the score. In fact, tables placed in the score are   
  created later than the initialization of the opcodes placed in the header   
  section of the orchestra.                                                   

itype -- an integer number denoting the appearance of the valuator.

The itype argument can be set to the following values:

  * 1 - a 3-D knob

  * 2 - a pie-like knob

  * 3 - a clock-like knob

  * 4 - a flat knob

A 3-D knob.

A pie knob.

A clock knob.

A flat knob.

idisp -- a handle value that was output from a previous instance of the
|flvalue| FLvalue opcode to display the current value of the current valuator
in the FLvalue widget itself. If the user doesn't want to use this feature
that displays current values, it must be set to a negative number by the
user.

iwidth -- width of widget.

iheight -- height of widget.

ix -- horizontal position of upper left corner of the valuator, relative to
the upper left corner of corresponding window (expressed in pixels).

iy -- vertical position of upper left corner of the valuator, relative to the
upper left corner of corresponding window (expressed in pixels).

icursorsize (optional) -- If FLknob's itype is set to 1 (3D knob), this
parameter controls the size of knob cursor.

Performance		~

kout -- output value

FLknob puts a knob in the corresponding container.

See Also		~

|flcount| FLcount, |fljoy| FLjoy, |flkeyb| FLkeyb, |flroller| FLroller,
|flslider| FLslider, |fltext| FLtext

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*fllabel*
FLlabel	~

FLlabel --  A FLTK opcode that modifies the appearance of a text label.

Description		~

Modifies a set of parameters related to the text label appearence of a widget
(i.e. size, font, alignment and color of corresponding text).

Syntax		~

FLlabel isize, ifont, ialign, ired, igreen, iblue

Initialization		~

isize -- size of the font of the target widget. Normal values are in the
order of 15. Greater numbers enlarge font size, while smaller numbers reduce
it.

ifont -- sets the the font type of the label of a widget.

Legal values for ifont argument are:

  * 1 - Helvetica (same as Arial under Windows)

  * 2 - Helvetica Bold

  * 3 - Helvetica Italic

  * 4 - Helvetica Bold Italic

  * 5 - Courier

  * 6 - Courier Bold

  * 7 - Courier Italic

  * 8 - Courier Bold Italic

  * 9 - Times

  * 10 - Times Bold

  * 11 - Times Italic

  * 12 - Times Bold Italic

  * 13 - Symbol

  * 14 - Screen

  * 15 - Screen Bold

  * 16 - Dingbats

ialign -- sets the alignment of the label text of the widget.

Legal values for ialign argument are:

  * 1 - align center

  * 2 - align top

  * 3 - align bottom

  * 4 - align left

  * 5 - align right

  * 6 - align top-left

  * 7 - align top-right

  * 8 - align bottom-left

  * 9 - align bottom-right

ired -- The red color of the target widget. The range for each RGB component
is 0-255

igreen -- The green color of the target widget. The range for each RGB
component is 0-255

iblue -- The blue color of the target widget. The range for each RGB
component is 0-255

Performance		~

FLlabel modifies a set of parameters related to the text label appearance of
a widget, i.e. size, font, alignment and color of corresponding text. This
opcode affects (almost) all widgets defined next its location. A user can put
several instances of FLlabel in front of each widget he intends to modify.
However, to modify a particular widget, it is better to use the opcode
belonging to the second type (i.e. those containing the ihandle argument).

The influence of FLlabel on the next widget can be turned off by using -1 as
its only argument. FLlabel is designed to modify text attributes of a group
of related widgets.

See Also		~

|flcolor| FLcolor, |flcolor2| FLcolor2, |flhide| FLhide, |flsetalign|
FLsetAlign, |flsetbox| FLsetBox, |flsetcolor| FLsetColor, |flsetcolor2|
FLsetColor2, |flsetfont| FLsetFont, |flsetposition| FLsetPosition,
|flsetsize| FLsetSize, |flsettext| FLsetText, |flsettextcolor|
FLsetTextColor, |flsettextsize| FLsetTextSize, |flsettexttype| FLsetTextType,
|flsetvali| FLsetVal_i, |flsetval| FLsetVal, |flshow| FLshow

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flloadsnap*
FLloadsnap	~

FLloadsnap --  Loads all snapshots into the memory bank of the current
orchestra.

Description		~

FLloadsnap loads all the snapshots contained in a file into the memory bank
of the current orchestra.

Syntax		~

FLloadsnap "filename"

Initialization		~

"filename" -- a double-quoted string corresponding to a file to load a bank
of snapshots.

Performance		~

FLloadsnap loads all snapshots contained in filename into the memory bank of
current orchestra.

See Also		~

|flgetsnap| FLgetsnap, |flrun| FLrun, |flsavesnap| FLsavesnap, |flsetsnap|
FLsetsnap, |flupdate| FLupdate

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flpack*
FLpack	~

FLpack --  Provides the functionality of compressing and aligning FLTK
widgets.

Description		~

FLpack provides the functionality of compressing and aligning widgets.

Syntax		~

FLpack iwidth, iheight, ix, iy, itype, ispace, iborder

Initialization		~

iwidth -- width of widget.

iheight -- height of widget.

ix -- horizontal position of upper left corner of the valuator, relative to
the upper left corner of corresponding window (expressed in pixels).

iy -- vertical position of upper left corner of the valuator, relative to the
upper left corner of corresponding window (expressed in pixels).

itype -- an integer number that modifies the appearance of the target widget.

The itype argument expresses the type of packing:

  * 0 - vertical

  * 1 - horizontal

ispace -- sets the space between the widgets.

iborder -- border type of the container. It is expressed by means of an
integer number chosen from the following:

  * 0 - no border

  * 1 - down box border

  * 2 - up box border

  * 3 - engraved border

  * 4 - embossed border

  * 5 - black line border

  * 6 - thin down border

  * 7 - thin up border

Performance		~

FLpack provides the functionality of compressing and aligning widgets.

Containers are useful to format the graphic appearance of the widgets. The
most important container is |flpanel| FLpanel, that actually creates a
window. It can be filled with other containers and/or valuators or other
kinds of widgets.

There are no k-rate arguments in containers.

Examples		~

The following example:

      FLpanel "Panel1",450,300,100,100
      FLpack  400,300, 10,40,0,15,3
 gk1,ihs1        FLslider        "FLslider 1", 500, 1000, 2 ,1, -1, 300,15, 20,50
 gk2,ihs2        FLslider        "FLslider 2", 300, 5000, 2 ,3, -1, 300,15, 20,100
 gk3,ihs3        FLslider        "FLslider 3", 350, 1000, 2 ,5, -1, 300,15, 20,150
 gk4,ihs4        FLslider        "FLslider 4", 250, 5000, 1 ,11, -1, 300,30, 20,200
 gk5,ihs5        FLslider        "FLslider 5", 220, 8000, 2 ,1, -1, 300,15, 20,250
 gk6,ihs6        FLslider        "FLslider 6", 1, 5000, 1 ,13, -1, 300,15, 20,300
 gk7,ihs7        FLslider        "FLslider 7", 870, 5000, 1 ,15, -1, 300,30, 20,350
      FLpackEnd
      FLpanelEnd

...will produce this result, when resizing the window:

FLpack.

See Also		~

|flgroup| FLgroup, |flgroupend| FLgroupEnd, |flpackend| FLpackEnd, |flpanel|
FLpanel, |flpanelend| FLpanelEnd, |flscroll| FLscroll, |flscrollend|
FLscrollEnd, |fltabs| FLtabs, |fltabsend| FLtabsEnd

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flpackend*
FLpackEnd	~

FLpackEnd --  Marks the end of a group of compressed or aligned FLTK widgets.

Description		~

Marks the end of a group of compressed or aligned FLTK widgets.

Syntax		~

FLpackEnd

Performance		~

Containers are useful to format the graphic appearance of the widgets. The
most important container is |flpanel| FLpanel, that actually creates a
window. It can be filled with other containers and/or valuators or other
kinds of widgets.

There are no k-rate arguments in containers.

See Also		~

|flgroup| FLgroup, |flgroupend| FLgroupEnd, |flpack| FLpack, |flpanel|
FLpanel, |flpanelend| FLpanelEnd, |flscroll| FLscroll, |flscrollend|
FLscrollEnd, |fltabs| FLtabs, |fltabsend| FLtabsEnd

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flpanel*
FLpanel	~

FLpanel --  Creates a window that contains FLTK widgets.

Description		~

Creates a window that contains FLTK widgets.

Syntax		~

FLpanel "label", iwidth, iheight [, ix] [, iy] [, iborder]

Initialization		~

"label" -- a double-quoted string containing some user-provided text, placed
near the corresponding widget.

iwidth -- width of widget.

iheight -- height of widget.

ix (optional) -- horizontal position of upper left corner of the valuator,
relative to the upper left corner of corresponding window (expressed in
pixels).

iy (optional) -- vertical position of upper left corner of the valuator,
relative to the upper left corner of corresponding window (expressed in
pixels).

iborder (optional) -- border type of the container. It is expressed by means
of an integer number chosen from the following:

  * 0 - no border

  * 1 - down box border

  * 2 - up box border

  * 3 - engraved border

  * 4 - embossed border

  * 5 - black line border

  * 6 - thin down border

  * 7 - thin up border

Performance		~

Containers are useful to format the graphic appearance of the widgets. The
most important container is |flpanel| FLpanel, that actually creates a
window. It can be filled with other containers and/or valuators or other
kinds of widgets.

There are no k-rate arguments in containers.

Examples		~

FLpanel creates a window. It must be followed by the opcode |flpanelend|
FLpanelEnd when all widgets internal to it are declared. For example:

      FLpanel   "PanelPluto",450,550,100,100 ;***** start of container
 gk1,ih1 FLslider  "FLslider 1", 500, 1000, 2 ,1, -1, 300,15, 20,50
 gk2,ih2 FLslider  "FLslider 2", 300, 5000, 2 ,3, -1, 300,15, 20,100
 gk3,ih3 FLslider  "FLslider 3", 350, 1000, 2 ,5, -1, 300,15, 20,150
 gk4,ih4 FLslider  "FLslider 4", 250, 5000, 1 ,11,-1, 300,30, 20,200
      FLpanelEnd ;***** end of container

will output the following result:

FLpanel.

See Also		~

|flgroup| FLgroup, |flgroupend| FLgroupEnd, |flpack| FLpack, |flpackend|
FLpackEnd, |flpanelend| FLpanelEnd, |flscroll| FLscroll, |flscrollend|
FLscrollEnd, |fltabs| FLtabs, |fltabsend| FLtabsEnd

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flpanelend*
FLpanelEnd	~

FLpanelEnd --  Marks the end of a group of FLTK widgets contained inside of a
window (panel).

Description		~

Marks the end of a group of FLTK widgets contained inside of a window
(panel).

Syntax		~

FLpanelEnd

Performance		~

Containers are useful to format the graphic appearance of the widgets. The
most important container is |flpanel| FLpanel, that actually creates a
window. It can be filled with other containers and/or valuators or other
kinds of widgets.

There are no k-rate arguments in containers.

See Also		~

|flgroup| FLgroup, |flgroupend| FLgroupEnd, |flpack| FLpack, |flpackend|
FLpackEnd, |flpanel| FLpanel, |flscroll| FLscroll, |flscrollend| FLscrollEnd,
|fltabs| FLtabs, |fltabsend| FLtabsEnd

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flprintk*
FLprintk	~

FLprintk --  A FLTK opcode that prints a k-rate value at specified intervals.

Description		~

FLprintk is similar to |printk| printk but shows values of a k-rate signal in
a text field instead of on the console.

Syntax		~

FLprintk itime, kval, idisp

Initialization		~

itime -- how much time in seconds is to elapse between updated displays.

idisp -- a handle value that was output from a previous instance of the
|flvalue| FLvalue opcode to display the current value of the current valuator
in the FLvalue widget itself. If the user doesn't want to use this feature
that displays current values, it must be set to a negative number by the
user.

Performance		~

kval -- k-rate signal to be displayed.

FLprintk is similar to |printk| printk, but shows values of a k-rate signal
in a text field instead of showing it in the console. The idisp argument must
be filled with the ihandle return value of a previous FLvalue opcode. While
FLvalue should be placed in the header section of an orchestra inside an
|flpanel| FLpanel/|flpanelend| FLpanelEnd block, FLprintk must be placed
inside an instrument to operate correctly. For this reason, it slows down
performance and should be used for debugging purposes only.

See Also		~

|flbox| FLbox, |flbutbank| FLbutBank, |flbutton| FLbutton, |flprintk2|
FLprintk2, |flvalue| FLvalue

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flprintk2*
FLprintk2	~

FLprintk2 --  A FLTK opcode that prints a new value every time a control-rate
variable changes.

Description		~

FLprintk2 is similar to |flprintk| FLprintk but shows a k-rate variable's
value only when it changes.

Syntax		~

FLprintk2 kval, idisp

Initialization		~

idisp -- a handle value that was output from a previous instance of the
|flvalue| FLvalue opcode to display the current value of the current valuator
in the FLvalue widget itself. If the user doesn't want to use this feature
that displays current values, it must be set to a negative number by the
user.

Performance		~

kval -- k-rate signal to be displayed.

FLprintk2 is similar to |flprintk| FLprintk, but shows the k-rate variable's
value only each time it changes. Useful for monitoring MIDI control changes
when using sliders. It should be used for debugging purposes only, since it
slows-down performance.

See Also		~

|flbox| FLbox, |flbutbank| FLbutBank, |flbutton| FLbutton, |flprintk|
FLprintk, |flvalue| FLvalue

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flroller*
FLroller	~

FLroller --  A FLTK widget that creates a transversal knob.

Description		~

FLroller is a sort of knob, but put transversally.

Syntax		~

kout, ihandle FLroller "label", imin, imax, istep, iexp, itype, idisp,
iwidth, iheight, ix, iy

Initialization		~

ihandle -- a handle value (an integer number) that unequivocally references a
corresponding widget. This is used by other opcodes that modify a widget's
properties (see |controlfltkappearance| Modifying FLTK Widget Appearance). It
is automatically output by FLroller and must not be set by the user label.
(The user label is a double-quoted string containing some user-provided text
placed near the widget.)

"label" -- a double-quoted string containing some user-provided text, placed
near the corresponding widget.

imin -- minimum value of output range.

imax -- maximum value of output range.

istep -- a floating-point number indicating the increment of valuator value
corresponding to of each mouse click. The istep argument allows the user to
arbitrarily slow roller's motion, enabling arbitrary precision.

iexp -- an integer number denoting the behaviour of valuator:

  * 0 = valuator output is linear

  * -1 = valuator output is exponential

All other positive numbers for iexp indicate the number of an existing table
that is used for indexing. Linear interpolation is provided in table
indexing. A negative table number suppresses interpolation.

  IMPORTANT!                                                                  
  Notice that the tables used by valuators must be created with the |ftgen|   
  ftgen opcode and placed in the orchestra before the corresponding valuator. 
  They can not placed in the score. In fact, tables placed in the score are   
  created later than the initialization of the opcodes placed in the header   
  section of the orchestra.                                                   

itype -- an integer number denoting the appearance of the valuator.

The itype argument can be set to the following values:

  * 1 - horizontal roller

  * 2 - vertical roller

idisp -- a handle value that was output from a previous instance of the
|flvalue| FLvalue opcode to display the current value of the current valuator
in the FLvalue widget itself. If the user doesn't want to use this feature
that displays current values, it must be set to a negative number by the
user.

iwidth -- width of widget.

iheight -- height of widget.

ix -- horizontal position of upper left corner of the valuator, relative to
the upper left corner of corresponding window (expressed in pixels).

iy -- vertical position of upper left corner of the valuator, relative to the
upper left corner of corresponding window (expressed in pixels).

Performance		~

kout -- output value

FLroller is a sort of knob, but put transversally:

FLroller.

See Also		~

|flcount| FLcount, |fljoy| FLjoy, |flkeyb| FLkeyb, |flknob| FLknob,
|flslider| FLslider, |fltext| FLtext

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flrun*
FLrun	~

FLrun --  Starts the FLTK widget thread.

Description		~

Starts the FLTK widget thread.

Syntax		~

FLrun

Performance		~

This opcode must be located at the end of all widget declarations. It has no
arguments, and its purpose is to start the thread related to widgets. Widgets
would not operate if FLrun is missing.

See Also		~

|flgetsnap| FLgetsnap, |flloadsnap| FLloadsnap, |flsavesnap| FLsavesnap,
|flsetsnap| FLsetsnap, |flupdate| FLupdate

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flsavesnap*
FLsavesnap	~

FLsavesnap --  Saves all snapshots currently created into a file.

Description		~

FLsavesnap saves all snapshots currently created (i.e. the entire memory
bank) into a file.

Syntax		~

FLsavesnap "filename"

Initialization		~

"filename" -- a double-quoted string corresponding to a file to store a bank
of snapshots.

Performance		~

FLsavesnap saves all snapshots currently created (i.e. the entire memory
bank) into a file whose name is filename. Since the file is a text file,
snapshot values can also be edited manually by means of a text editor. The
format of the data stored in the file is the following (at present time, this
could be changed in next Csound version):

 ----------- 0 -----------
 FLvalue 0 0 1 0 ""
 FLvalue 0 0 1 0 ""
 FLvalue 0 0 1 0 ""
 FLslider 331.946 80 5000 -1 "frequency of the first oscillator"
 FLslider 385.923 80 5000 -1 "frequency of the second oscillator"
 FLslider 80 80 5000 -1 "frequency of the third oscillator"
 FLcount 0 0 10 0 "this index must point to the location number where snapshot is stored"
 FLbutton 0 0 1 0 "Store snapshot to current index"
 FLbutton 0 0 1 0 "Save snapshot bank to disk"
 FLbutton 0 0 1 0 "Load snapshot bank from disk"
 FLbox 0 0 1 0 ""
 ----------- 1 -----------
 FLvalue 0 0 1 0 ""
 FLvalue 0 0 1 0 ""
 FLvalue 0 0 1 0 ""
 FLslider 819.72 80 5000 -1 "frequency of the first oscillator"
 FLslider 385.923 80 5000 -1 "frequency of the second oscillator"
 FLslider 80 80 5000 -1 "frequency of the third oscillator"
 FLcount 1 0 10 0 "this index must point to the location number where snapshot is stored"
 FLbutton 0 0 1 0 "Store snapshot to current index"
 FLbutton 0 0 1 0 "Save snapshot bank to disk"
 FLbutton 0 0 1 0 "Load snapshot bank from disk"
 FLbox 0 0 1 0 ""
 ----------- 2 -----------
 ..... etc...
 ----------- 3 -----------
 ..... etc...
 ---------------------------

As you can see, each snapshot contain several lines. Each snapshot is
separated from previous and next snapshot by a line of this kind:

"----------- snapshot Num -----------"

Then there are several lines containing data. Each of these lines corresponds
to a widget.

The first field of each line is an unquoted string containing opcode name
corresponding to that widget. Second field is a number that expresses current
value of a snapshot. In current version, this is the only field that can be
modified manually. The third and fourth fields shows minimum and maximum
values allowed for that valuator. The fifth field is a special number that
indicates if the valuator is linear (value 0), exponential (value -1), or is
indexed by a table interpolating values (negative table numbers) or
non-interpolating (positive table numbers). The last field is a quoted string
with the label of the widget. Last line of the file is always

"---------------------------"

.

See Also		~

|flgetsnap| FLgetsnap, |flloadsnap| FLloadsnap, |flrun| FLrun, |flsetsnap|
FLsetsnap, |flupdate| FLupdate

Credits		~

Author: Gabriel Maldonado

New in version 4.22

------------------------------------------------------------------------------
*flscroll*
FLscroll	~

FLscroll --  A FLTK opcode that adds scroll bars to an area.

Description		~

FLscroll adds scroll bars to an area.

Syntax		~

FLscroll iwidth, iheight [, ix] [, iy]

Initialization		~

iwidth -- width of widget.

iheight -- height of widget.

ix (optional) -- horizontal position of upper left corner of the valuator,
relative to the upper left corner of corresponding window (expressed in
pixels).

iy (optional) -- vertical position of upper left corner of the valuator,
relative to the upper left corner of corresponding window (expressed in
pixels).

Performance		~

Containers are useful to format the graphic appearance of the widgets. The
most important container is |flpanel| FLpanel, that actually creates a
window. It can be filled with other containers and/or valuators or other
kinds of widgets.

There are no k-rate arguments in containers.

FLscroll adds scroll bars to an area. Normally you must set arguments iwidth
and iheight equal to that of the parent window or other parent container. ix
and iy are optional since they normally are set to zero. For example the
following code:

      FLpanel   "PanelPluto",400,300,100,100
      FLscroll  400,300
 gk1,ih1 FLslider  "FLslider 1", 500, 1000, 2 ,1, -1, 300,15, 20,50
 gk2,ih2 FLslider  "FLslider 2", 300, 5000, 2 ,3, -1, 300,15, 20,100
 gk3,ih3 FLslider  "FLslider 3", 350, 1000, 2 ,5, -1, 300,15, 20,150
 gk4,ih4 FLslider  "FLslider 4", 250, 5000, 1 ,11,-1, 300,30, 20,200
      FLscrollEnd
      FLpanelEnd

wi