Release Notes for Csound 4.24.0 (unofficial version by Istvan Varga)
===============================
This document lists all changes as compared to canonical Csound
version 4.23. Manuals for new opcodes and utilities are also included.
Bug fixes
---------
* Bugs in vco PWM and triangle mode are fixed. Also, amplitude of
PWM wave was corrected, and triangle amplitude depends much
less on pulse width.
* FLTK widgets may now compile with FLTK 1.0.x
* <sstream> or <strstream> interface can be selected at compile time
to fix compile errors
* typo in usage message (score,srt) corrected
* temporary files in Win32 version may now work. Directories are
searched in the following order: %SFDIR%, %TEMP%, %WINDIR%\TEMP
* fixes in reading Unix/MS-DOS/Mac format orchestra, score, and CSD
files (the disadvantage is that the new version does not check for
comments continuing in another file or macro)
* maximum line length in CSD files extended to more than 500
characters (was 200)
* corrected "Invalid ftable no. %f" error message in MIDI controller
opcodes
* amplitude bug in adsyn has been fixed (reported by Kevin Conder)
* if/else/endif internal labels use less trivial names to avoid
conflicts with user labels (e.g. "__else_2317" instead of "else1")
* Win32 MIDI in devices can be selected by number, in addition to
name, making it easier to use devices with a name that contains
spaces. (bug reported by Oeyvind Brandtsegg)
* setting cursor size in FLknob now works. (bug reported by
Josep M Comajuncosas)
* FLbutBank widget size bug has been fixed.
(bug reported by Oeyvind Brandtsegg)
* fixed reading of Base64 encoded files.
* fixed bugs in <CsFileB> and <CsSampleB> CSD tags.
* incorporated bqrez changes from Matt Gerassimoff.
* max_k in average mode has been fixed (output was multiplied by
ksmps)
* syntax errors in lines that have a ';' comment are now printed
correctly
* minor bug in setksmps has been fixed
* --hardwarebufsamps=N option now sets the hardware buffer size
correctly
* audio device selection under Win32 should be fixed
(bug reported by Josep M Comajuncosas)
* fixes in various opcodes related to use with local ksmps
* compile errors in widgets.cpp reported by Steven Yi have been
fixed
* i() with expression argument is now a syntax error if
--expression-opt is turned on, and a warning is printed otherwise.
Note that using i() with an expression as argument can produce
unexpected results, so it is recommended to avoid this type of
usage.
* bug in --expression-opt with multiple expressions on the same
line is fixed.
* delayr/delayw and Win32 real-time audio input are reset correctly
in case of re-entrant operation (does not affect current binary
distributions).
* bug in delayr with 64 bit floats has been fixed.
* fixed bug that caused any label name that begins with "else" or
"endif" to be rejected.
* other minor fixes, compiler warnings, etc. (see changelogs)
* fixed 'square knobs' FLknob bug reported by Oeyvind Brandtsegg
* usage message under Win32 is now really printed to stdout
* attempts to fix bugs that resulted in an error return after
listing opcodes, printing help message, or calling utilities
even though there was no error in fact
* rtclock bug that made it impossible to use the opcode has been
fixed
* clockon/clockoff/readclock fixed
* -t<tempo> flag fixed so that it now actually has effect
* fixed bug in beat mode that could result in hangs in case of very
short time intervals
* fixes in sensekey - now seems to work under Win32 and Linux
(note: it reads characters from stdin, so it is not possible to
use stdin for other purposes - such as audio input - at the same
time. Also, to receive keyboard input, the console window in
which Csound is being run must be the active window.)
* printk2 now prints the first value if it is zero
Language Changes
----------------
* Parsing of large orchestras was made faster.
* 32767 k-periods limit on release time (xtratim) removed; now it
can be more than two billion k-periods (i.e. more than 3 hours
even with kr = 192000)
* new command line option (--expression-opt) that turns on some
optimizations in expressions:
* redundant assignment operations are eliminated whenever
possible. This means that for example this line
a1 = a2 + a3
will compile as
a1 Add a2, a3
instead of
#a0 Add a2, a3
a1 = #a0
saving a temporary variable and an opcode call. Less opcode
calls result in reduced CPU usage (an average orchestra may
compile about 10% faster with --expression-opt, but it
depends largely on how many expressions are used, what the
control rate is (see also below), etc.; thus, the difference
may be less, but also much more).
* number of a- and k-rate temporary variables is significantly
reduced. This expression
(a1 + a2 + a3 + a4)
will compile as
#a0 Add a1, a2
#a0 Add #a0, a3
#a0 Add #a0, a4 ; (the result is in #a0)
instead of
#a0 Add a1, a2
#a1 Add #a0, a3
#a2 Add #a1, a4 ; (the result is in #a2)
The advantages of less temporary variables are:
* less cache memory is used, which may improve performance
of orchestras with many a-rate expressions and a low
control rate (e.g. ksmps = 100)
* large orchestras may load faster due to less different
identifier names
* index overflow errors (i.e. when messages like this
Case2: indx=-56004 (ffff253c); (short)indx = 9532 (253c)
are printed and odd behavior or a Csound crash occurs) may
be fixed, because such errors are triggered by too many
different (especially a-rate) variable names in a single
instrument.
Note that this optimization (due to technical reasons) is not
performed on i-rate temporary variables.
NOTE: when --expression-opt is turned on, it is not allowed to
use the i() function with an expression argument.
* beat mode (-t n command line option) is closer to fully working,
but still not perfect
* turnoff/release/MIDI note off code extensively revised (partly
due to removed xtratim limit). May have fixed some bugs, and
(hopefully not) introduced some new ones.
Opcode Fixes
------------
* Seeding random numbers from the clock in rand etc is now at higher
resolution in Windows and Linux (and probably other UNIX-like
systems).
* rtclock fixed and Windows version has higher resolution now.
* midiin works on all systems and both with real-time and MIDI file
input.
* Bugs in lowres/lowresx have been fixed.
* vco2init bug in selecting default table size is fixed.
New or modified opcodes
-----------------------
* bqrez: a second-order multi-mode filter (Matt Gerassimoff;
revised in version 4.23.4.2)
* subinstrinit: same as subinstr, but i-time only and has no output
arguments.
* nstrnum: returns the number of a named instrument.
* denorm a1[, a2[, a3[, ... ]]]
mixes low level (~1e-20 for floats, and ~1e-56 for doubles)
noise to a list of a-rate signals. Useful on Intel CPUs to
avoid "denormals".
* kr delayk ksig, idel[, imode]
k-rate delay with fixed delay time
* kr vdel_k ksig, kdel, imdel[, imode]
k-rate delay with variable delay time
* Several new opcodes for arithmetics (can be more efficient than
expressions, but see also --expression-opt):
xsig1 Add xsig2, xsig3 - xsig1 = xsig2 + xsig3
xsig1 Sub xsig2, xsig3 - xsig1 = xsig2 - xsig3
xsig1 sub xsig2, xsig3 - xsig1 = xsig2 - xsig3
xsig1 Mul xsig2, xsig3 - xsig1 = xsig2 * xsig3
xsig1 mul xsig2, xsig3 - xsig1 = xsig2 * xsig3
xsig1 Div xsig2, xsig3 - xsig1 = xsig2 / xsig3
xsig1 div xsig2, xsig3 - xsig1 = xsig2 / xsig3
vincr xsig1, xsig2 - xsig1 = xsig1 + xsig2
vdecr xsig1, xsig2 - xsig1 = xsig1 - xsig2
vmul xsig1, xsig2 - xsig1 = xsig1 * xsig2
vdiv xsig1, xsig2 - xsig1 = xsig1 / xsig2
Inc xsig - xsig = xsig + 1
Dec xsig - xsig = xsig - 1
dec xsig - xsig = xsig - 1
shl xsig - xsig = xsig + xsig
sqr xsig - xsig = xsig * xsig
* FLsetVal implemented (ported from CsoundAV 0.04)
* some opcode aliases added for CsoundAV compatibility:
ftlen2(): same as ftlen()
tab_i: same as i-time tab
tabw_i: same as i-time tabw
* schedwhen supports named instruments
* rbjeq:
parametric equalizer with 7 filter types (see below)
* schedwhenname, schedkwhenname, eventname:
for compatibility with canonical Csound (note that it is
possible to use both named instruments and k-rate instrument
numbers with schedwhen, schedkwhen, and event, so the above
opcodes are actually redundant)
* many opcodes were ported from CsoundAV (these are not tested yet):
tab, tabw: fast ftable access, also non-power of two
metro: generates k-rate impulses at a given frequency
vdelayk: another k-rate delay (not the same as the 4.23.2
one which was renamed to vdel_k)
mandel: Mandelbrot fractals
vcella: a cellular automata
zr(): access zak space from expressions
tb0_init, tb1_init, ..., tb15_init:
tb0(), tb1(), ..., tb15():
access ftables from expressions (i- and k-rate only)
changed: checks if any of the given k-rate variables have
been changed
max_k: maximum or average value of a signal (documentation
is not available yet)
* FLpack has three new optional arguments (see CsoundAV manual)
* distort1 has a new optional argument that defaults to zero, and
selects amplitude scaling mode:
aout distort1 ain, kpregain, kpostgain, kshape1, kshape2[, imode]
imode = 0 (default, compatible with original version):
aout = (exp(ain * (pregain / 5000 + shape1 / 8000))
- exp(-ain * (pregain / 5000 + shape2 / 8000)))
/ (exp(ain * pregain / 5000) + exp(-ain * pregain / 5000))
* postgain * 20000
imode = 1 (same as above, but with 0dbfs support):
aout = (exp(ain * (pregain * 0.625 + shape1) * 4.096 / 0dbfs)
- exp(-ain * (pregain * 0.625 + shape2) * 4.096 / 0dbfs))
/ (exp(ain * pregain * 6.5536 / 0dbfs)
+ exp(-ain * pregain * 6.5536 / 0dbfs))
* postgain * 0dbfs * 0.61035
imode = 2 ("raw" mode; notice the different calculation for shape1
and shape2):
aout = (exp(ain * pregain * (1 + shape1))
- exp(-ain * pregain * (1 + shape2)))
/ (exp(ain * pregain) + exp(-ain * pregain))
* postgain
* readclock can be used at both init and control rate, depending
on output argument type. There is also a new optional input
parameter, which requests a CPU time value if set to zero (this
is the default), and real time if non-zero. The returned value
is always in millisecond units, but the resolution may vary
depending on the selected mode and system:
Win32 Linux/x86 UNIX other
CPU time 1 ms (1 / HZ) sec ? ?
real time < 1 us CPU cycle 1 us 1 sec
Note: HZ is 100 by default, but can be modified in kernel sources
"CPU cycle" is e.g. 1 ns for a 1 GHz CPU
The syntax of the new readclock opcode is
ir readclock indx[, imode]
kr readclock kndx[, imode]
see also the example CSD below.
New Gens
--------
None
Other Changes:
-------------
* Realtime MIDI under Windows may now work ?
* Real-time audio using ALSA interface (allows multichannel, high
resolution sample formats, device selection, more control over
latency and timing jitter, and more) under Linux is now possible.
* Full duplex operation with OSS audio interface under Linux may work.
* Attempts to fix the hang when closing all FLTK windows.
* Benchmark information (elapsed real and CPU time) can be printed
with -m128 flag. Tested under Win32 and Linux.
* subinstr reworked (several bug fixes and optimizations).
* xtratim/linsegr/etc. allowed in score notes even with finite length
(p3 > 0). Not fully tested.
* Bugs in expanding instrument numbers have been fixed.
* Both FLpanel_end and FLpanelEnd style syntax is allowed in FLTK
containers.
* On Ctrl-C interrupts, soundfile header is updated before exiting
(may not be available on all systems).
* use of string database (csound.xmg) was made optional at compile
time, and is disabled by default
* distort1 optimized for speed
* minor optimizations in orchestra parser
also in bqrez opcode
* preprocessed orchestra (with include files and macros expanded)
can be written to a file with --write-orc=FNAME option; useful
for debugging large orchestras with many macros and include files.
Unfortunately strips ';' comments (leaves only the ';' character).
* MacOS X real-time audio synchronized with canonical version (not
tested)
* delayr has a new optional i-time output, and all deltap opcodes
have a new optional i-time input argument that defaults to zero.
These optional parameters can be used to select a particular
delay line to be used by deltap/deltapx/etc. in case of nested
delays. The following example should explain how to use the
new arguments:
; delayr returns delay index as a negative integer in an
; optional i-time output variable
a1, indx1 delayr idel1 ; indx1 is set to -1
a2, indx2 delayr idel2 ; indx2 is set to -2
a3, indx3 delayr idel3 ; indx3 is set to -3
; all deltap opcodes have a new optional i-time parameter that
; defaults to zero (for compatibility). If this is zero or
; positive, delay lines are indexed backwards.
atap1 deltapi idt1, 0 ; reads from 3rd delay line
atap2 deltapi idt2, 1 ; reads from 2nd delay line
atap3 deltapi idt3, 2 ; reads from 1st delay line
;atap4 deltapi idt4, 3 ; (would be an error)
; if the optional parameter is negative, delay lines are
; indexed forwards. Note that the optional output of delayr
; can be used as a handle to select delays.
atap1 deltapi idt1, -1 ; uses 1st delay line
atap1 deltapi idt1, indx1
atap2 deltapi idt2, -2 ; uses 2nd delay line
atap2 deltapi idt2, indx2
atap3 deltapi idt3, -3 ; uses 3rd delay line
atap3 deltapi idt3, indx3
;atap4 deltapi idt4, -4 ; (would be an error)
delayw asig1 ; writes to 1st delay line
; and closes it
; this is wrong, because it would in fact read from the 2nd
; delay line (which has now become the first)
;atap5 deltapi idt5, indx1
delayw asig2 ; writes to 2nd delay line
delayw asig3 ; writes to 3rd delay line
* deltapx/deltapxw with sinc interpolation revised for speed.
* new Win32 real-time audio code, with some new options:
* --sched set real-time scheduling priority (dangerous,
may hang the system)
* --sched=N set scheduling priority to:
N=0: real-time, N=1: high, N=2: normal
(the default is normal priority)
* --rt-sleep=N wait for N (the expected range is 0 to 10)
milliseconds between polling buffers.
Increasing this yields more CPU time to other
applications, and setting to zero results in
all available CPU time being used by the
Csound audio thread. The default is 1.
* --rt-hdr use method of canonical Csound for preparing
buffers
* --no-rt-hdr use method of CsoundAV for preparing buffers
(this is the default)
of the last two options, select whichever gives better results.
Also, -b sets the audio buffer size (this was originally -B),
and (-B / -b) is the number of buffers. For example,
-b 200 -B 4000 means 20 buffers of 200 samples (originally the
number of buffers was hard-coded to 4 in canonical Csound).
* usage message under Win32 is now printed to stdout instead of
stderr, so it can be redirected, or read with 'more'.
* massign can "mute" MIDI channels by assigning to zero or negative
instrument number. Useful when midiin opcode is used to parse
MIDI events.
* bqrez opcode updated to new version from Matt Gerassimoff, also
fixed some bugs.
* Named instruments can be invoked as opcodes, as requested by Matt
J. Ingalls, using subinstr-like syntax:
a1[, a2[, ... ]] Name p4[, p5[, p6[, ... ]]]
Note however, that if both a named instrument and an user defined
opcode are defined with the same name, the opcode will have
precedence over the instrument (of course, the latter is still
callable with subinstr).
* Incorporated new printf opcodes from Matt Ingalls. The new version
of "printks" is currently named "sprintks" in order to avoid
breaking the original "printks", until the new code is fully
tested.
* schedule now supports named instruments.
* sfont opcodes synchronized with jpff 4.23 version.
* Crashes in (some) utilities have been fixed - still needs to be
fully cleaned up.
* Internal opcode names like "oscil_kk", "peak_k", "oscilikt_aa",
etc. have been all renamed to use a dot instead (thus "oscil_kk"
is now "oscil.kk", for example). This avoids conflicts with normal
opcode names like "FLpanel_end".
* Many internal code changes - see changelogs for details.
* the Winsound GUI and all related code was removed from the
sources
* there is a new command line option (--write-sco=FNAME) that
requests writing the sorted score to the specified file instead
of score.srt or a temporary file. This file is not deleted on
exit. N.B. see also --write-orc=FNAME option that writes the
preprocessed (include files and macros expanded) orchestra to a
file.
* improved measurement of real time (higher resolution),
particularly under Win32 and Linux (see readclock changes above
for details) on x86 machines. This affects all the following:
* rtclock opcode
* clockon/clockoff/readclock opcodes
* benchmark information printed by -m128 flag
* seeding from time in rand, randh, randi, pinkish, rnd31,
spat3d, and unirand, trirand, and all related opcodes.
Due to the CPU cycle time resolution under Linux/x86, these
opcodes never generate the same random sequence when seeding
from current time, even if called within very short time
intervals.
* 'ftable <number>:' messages are not printed if message level is
set to zero - this is useful when there are many function tables,
and the printing of large number of messages is not desired.
* 'util UTILNAME:' messages are now printed to stderr instead of
stdout
* a-rate rnd31 with uniform distribution was made faster.
* many stand-alone utilities (cvanal, dnoise, hetro, lpanal,
pvanal, pvlook, and sndinfo) have been replaced by a simple
wrapper utility that calls 'csound -U utilname args ...', where
csound is replaced by the value of the CSOUND environment
variable, if it is set. This preserves the functionality of the
old stand-alone utilities (it is still possible to call e.g.
cvanal foo.wav foo.cv), while reducing distribution size.
* a major internal reorganization of sources, with many changes
that are mostly of interest only to developers (details can be
found in ChangeLog.4.24.0). The most relevant of these are:
integration of csound.c and csound.h from Michael Gogins (there
are several changes compared to the original files), removal of
jpff_glue.c, completely different use of globals, and revised
stand-alone utilities. In addition, changes were made to the
plugin opcode interface that make it possible to have a separate
init function for 32 and 64 bit floats, and changes in the size
of OENTRY are less likely to break plugins. Both the API and
plugin code are experimental (this in general does not affects
the csound stand-alone executable) and are subject to changes.
Plugins compiled for canonical Csound are NOT supported.
New utilities
-------------
* csb64enc [OPTIONS ... ] infile1 [ infile2 [ ... ]]
converts a set of files to <CsFileB> tags (for detailed manual
see below)
* makecsd [OPTIONS ... ] infile1 [ infile2 [ ... ]]
creates a CSD file from a set of input files
* cs [-OPTIONS] <name> [CSOUND OPTIONS ... ]
Csound launcher utility (saves typing)
Windows GUI Changes
-------------------
The Winsound GUI has been removed from the sources.
=======================================================================
MANUALS
=======================================================================
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) -- low-pass, high-pass, band-pass,
band-reject, or all-pass mode:
0 = low-pass (default)
1 = high-pass
2 = band-pass
3 = band-reject
4 = all-pass
Performance
asig -- input signal
xfco -- filter cut-off frequency in Hz. As of version 3.50, may i-,k-,
or a-rate.
xres -- amount of resonance. Values of 1 to 100 are typical. Resonance
should be one or greater. 100 gives a 20dB gain at the cutoff
frequency.
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.
All filter modes can be frequency modulated as well as the the resonance
can also be frequency modulated.
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 32000, 220, 1
; Vary the filter-cutoff frequency from .2 to 2 KHz.
kfco line 200, p3, 200
; Set the resonance amount to one.
kres init 25
a1 bqrez asig, kfco, kres
out a1
endin
/* bqrez.orc */
/* bqrez.sco */
/* Written 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, moogvcf, rezzy
Credits
Author: Matt Gerassimoff
November 2002
-----------------------------------------------------------------------
ar rbjeq asig, kfco, klvl, kQ, kS[, imode]
DESCRIPTION
-----------
Parametric equalizer and filter opcode with 7 filter types, based on
algorithm by Robert Bristow-Johnson.
INITIALIZATION
--------------
imode (optional, defaults to zero) - sum of:
1: skip initialization (should be used in tied, or re-initialized
notes only).
and exactly one of the following values to select filter type:
0: resonant lowpass filter. kQ controls the resonance: at the
cutoff frequency (kfco), the amplitude gain is kQ (e.g. 20 dB
for kQ = 10), and higher kQ values result in a narrower
resonance peak. If kQ is set to sqrt(0.5) (about 0.7071),
there is no resonance, and the filter has a response that is
very similar to that of butterlp. If kQ is less than sqrt(0.5),
there is no resonance, and the filter has a -6 dB / octave
response from about kfco * kQ to kfco. Above kfco, there is
always a -12 dB / octave cutoff.
NOTE: the rbjeq lowpass filter is basically the same as
ar pareq asig, kfco, 0, kQ, 2
but is faster to calculate.
2: resonant highpass filter. The parameters are the same as for
the lowpass filter, but the equivalent filter is butterhp if
kQ is 0.7071, and "ar pareq asig, kfco, 0, kQ, 1" in other
cases.
4: bandpass filter. kQ controls the bandwidth, which is kfco / kQ,
and must be always less than sr / 2. The bandwidth is measured
between -3 dB points (i.e. amplitude gain = 0.7071), beyond
which there is a +/- 6 dB / octave slope.
This filter type is very similar to
ar butterbp asig, kfco, kfco / kQ
6: band-reject filter, with the same parameters as the bandpass
filter, and a response similar to that of butterbr.
8: peaking EQ. It has an amplitude gain of 1 (0 dB) at 0 Hz and
sr / 2, and klvl at the center frequency (kfco). Thus, klvl
controls the amount of boost (if it is greater than 1), or
cut (if it is less than 1). Setting klvl to 1 results in a
flat response. Similarly to the bandpass and band-reject
filters, the bandwidth is determined by kfco / kQ (which must
be less than sr / 2 again); however, this time it is between
sqrt(klvl) points (or, in other words, half the boost or cut
in decibels).
NOTE: excessively low or high values of klvl should be avoided
(especially with 32-bit floats), though the opcode was tested
with klvl = 0.01 and klvl = 100. klvl = 0 is always an error,
unlike in the case of pareq, which does allow a zero level.
10: low shelf EQ, controlled by klvl and kS (kQ is ignored by this
filter type). There is an amplitude gain of klvl at zero
frequency, while the level of high frequencies (around sr / 2)
is not changed. At the corner frequency (kfco), the gain is
sqrt(klvl) (half the boost or cut in decibels). The kS
parameter controls the steepness of the slope of the frequency
response (see below).
12: high shelf EQ. Very similar to the low shelf EQ, but affects
the high frequency range.
the default value for imode is zero (lowpass filter, initialization
not skipped).
PERFORMANCE
-----------
ar - the output signal.
asig - the input signal.
NOTE: if the input contains silent sections, on Intel CPUs a
significant slowdown can occur due to denormals. In such cases, it
is recommended to process the input signal with "denorm" opcode
before filtering it with rbjeq (and actually many other filters).
kfco - cutoff, corner, or center frequency, depending on filter type,
in Hz. It must be greater than zero, and less than sr / 2 (the range
of about sr * 0.0002 to sr * 0.49 should be safe).
klvl - level (amount of boost or cut), as amplitude gain (e.g. 1: flat
response, 4: 12 dB boost, 0.1: 20 dB cut); zero or negative values
are not allowed. It is recognized by the peaking and shelving EQ
types (8, 10, 12) only, and is ignored by other filters.
kQ - resonance (also kfco / bandwidth in many filter types). Not used
by the shelving EQs (imode = 10 and 12). The exact meaning of this
parameter depends on the filter type (see above), but it should be
always greater than zero, and usually (kfco / kQ) less than sr / 2.
kS - shelf slope parameter for shelving filters. Must be greater than
zero; a higher value means a steeper slope, with resonance if
kS > 1 (however, a too high kS value may make the filter unstable).
If kS is set to exactly 1, the shelf slope is as steep as possible
without a resonance. Note that the effect of kS - especially if it
is greater than 1 - also depends on klvl, and it does not have any
well defined unit.
EXAMPLE
-------
; ---- orchestra ----
sr = 44100
ksmps = 10
nchnls = 1
instr 1
a1 vco2 10000, 155.6 ; sawtooth wave
kfco expon 8000, p3, 200 ; filter frequency
a1 rbjeq a1, kfco, 1, kfco * 0.005, 1, 0 ; resonant lowpass
out a1
endin
; ---- score ----
i 1 0 5
e
AUTHORS
-------
Original algorithm by Robert Bristow-Johnson
Csound orchestra version by Josep M Comajuncosas, Aug 1999
Converted to C (with optimizations and bug fixes) by Istvan Varga,
Dec 2002
-----------------------------------------------------------------------
kr delayk ksig, idel[, imode]
kr vdel_k ksig, kdel, imdel[, imode]
DESCRIPTION
-----------
k-rate delay opcodes.
INITIALIZATION
--------------
idel - delay time (in seconds) for delayk. It is rounded to the
nearest integer multiple of a k-cycle (i.e. 1/kr).
imode - sum of:
1: skip initialization (e.g. in tied notes)
2: hold the first input value during the initial delay, instead of
outputting zero. This is mainly of use when delaying envelopes
that do not start at zero.
^__ imode = 0 ^ ___
| \ | | \
| \ => | | \
| \ | | \
-+------------> -+------------>
| |
^__ imode = 2 ^______
| \ | \
| \ => | \
| \ | \
-+------------> -+------------>
| |
imdel - maximum delay time for vdel_k, in seconds.
PERFORMANCE
-----------
kr - the output signal. Note: none of the opcodes interpolate the
output.
ksig - the input signal.
kdel - delay time (in seconds) for vdel_k. It is rounded to the
nearest integer multiple of a k-cycle (i.e. 1/kr).
AUTHOR
------
Istvan Varga
Dec 2002
=======================================================================
NOTE: all the following opcodes are by Gabriel Maldonado
_________________________________________________________________
tab, tabw
ir tab indx, ifn[, ixmode]
kr tab kndx, ifn[, ixmode]
ar tab xndx, ifn[, ixmode]
tabw isig, indx, ifn [,ixmode]
tabw ksig, kndx, ifn [,ixmode]
tabw asig, andx, ifn [,ixmode]
DESCRIPTION
Fast table opcodes. Faster than table and tablew because don't allow
wrap-around and limit and don't check index validity. Have been
implemented in order to provide fast access to arrays. Support
non-power of two tables (can be generated by any GEN function by
giving a negative length value).
INITIALIZATION
ifn - table number
ixmode (optional; default = 0) - ==0 - xndx and ixoff ranges match
the length of the table.
!=0 - xndx
and ixoff have a 0 to 1 range.
isig - input value to write
indx - table index
PERFORMANCE
asig, ksig - input signal to write
andx, kndx - table index
tab and tabw opcodes are similar to table and tablew, but are faster
and support tables having non-power-of-two length.
Special care of index value must be taken into account. Index values
out of the table allocated space will crash Csound.
_________________________________________________________________
Trigger Metronome
ktrig metro kfreq [, initphase]
DESCRIPTION
Generate a metronomic signal to be used in any circumstance an
isochronous trigger is needed.
INITIALIZATION
initphase - initial phase value (in the 0 to 1 range)
PERFORMANCE
ktrig - output trigger signal
kfreq - frequency of trigger bangs in cps
metro is a simple opcode that outputs a sequence of isochronous bangs
(that is 1 values) each 1/kfreq seconds. Trigger signals can be used
in any circumstance, mainly to temporize realtime algorithmic
compositional structures.
_________________________________________________________________
Mandelbrot Set
kiter, koutrig mandel ktrig, kx, ky, kmaxIter
DESCRIPTION
Returns the number of iterations corresponding to a given point of
complex plane by applying the Mandelbrot set formula.
PERFORMANCE
kiter- number of iterations
koutrig - output trigger signal
ktrig - input trigger signal
kx, ky - coordinates of a given point belonging to the complex plane
kmaxIter - maximum iterations allowed
mandel is an opocode that allows to use the Mandelbrot set formula to
generate an output that can be applied to any musical (or non-musical)
parameter. It has two output arguements, kiter, that contains the
iteration number of a given point, and koutrig, that generates a
trigger bang each time kiter changes. A new number of iterations is
evaluated only when ktrig is set to a non-zero value. User have to set
the coordinates of the complex plane inside kx and ky arguments, while
kmaxIter contains the maximum number of iteration the user intend to
use. Output values, that are integer numbers, can be mapped in any
sorts of ways by the composer.
_________________________________________________________________
K-rate Variable Time Delay
kr, vdelayk ksig, kdel, imaxdel [, iskip, imode]
DESCRIPTION
Variable delay applied to a k-rate signal
INITIALIZATION
imaxdel - maximum value of delay in seconds.
iskip (optional) - Skip initialization if present and non zero.
imode (optional) - if non-zero it suppresses linear interpolation.
While, normally, interpolation increases the quality of a signal, it
should be suppressed if using vdelay with discrete control signals,
such as, for example, trigger signals.
PERFORMANCE
kr - delayed output signal
ksig - input signal
kdel - delay time in seconds can be varied at k-rate
vdelayk is similar to vdelay, but works at k-rate. It is designed to
delay control signals, to be used, for example, in algorithmic
composition.
_________________________________________________________________
Cellular Automata
vcella ktrig, kreinit, ioutFunc, initStateFunc, iRuleFunc, ielements,
irulelen [, iradius]
DESCRIPTION
Unidimensional Cellular Automata applied to Csound vectors
INITIALIZATION
ioutFunc - number of the table where the state of each cell is stored
initStateFunc - number of a table containig the inital states of each
cell
iRuleFunc - number of a lookup table containing the rules
ielements - total number of cells
irulelen - total number of rules
iradius (optional) - radius of Cellular Automata. At present time CA
radius can be 1 or 2 (1 is the default)
PERFORMANCE
ktrig - trigger signal. Each time it is non-zero, a new generation of
cells is evaluated
kreinit - trigger signal. Each time it is non-zero, state of all cells
is forced to be that of initStateFunc.
vcella supports unidimensional cellular automata, where the state of
each cell is stored in ioutFunc. So ioutFunc is a vector containing
current state of each cell. This variant vector can be used together
with any other vector-based opcode, such as adsynt, vmap, vpowv etc.
initStateFunc is an input vector containing the inital value of the
row of cells, while iRuleFunc is an input vector containing the rules
in the form of a lookup table. Notice that initStateFunc and iRuleFunc
can be updated during the performance by means of other vector-based
opcodes (for example vcopy) in order to force to change rules and
status at performance time.
A new generation of cells is evaluated each time ktrig contains a
non-zero value. Also the status of all cells can be forced to assume
the status corresponding to the contents of initStateFunc each time
kreinit contains a non-zero value.
Radius of CA algorithm can be 1 or 2 (optional iradius arguement).
_________________________________________________________________
ZAK space read access inside expressions
iout = zr(iIndex)
kout = zr(kIndex)
aout = zr(aIndex)
DESCRIPTION
Allow to read ZAK space inside expressions.
These opcodes are identical to zir, zkr and zar, but can be used in
function fashion.
_________________________________________________________________
Table Read Access inside expressions
tb0_init ifn
tb1_init ifn
....
tb15_init ifn
iout = tb0(iIndex)
kout = tb0(kIndex)
iout = tb1(iIndex)
kout = tb1(kIndex)
....
iout = tb15(iIndex)
kout = tb15(kIndex)
DESCRIPTION
Allow to read tables in function fashion, to be used inside
expressions
At present time Csound only supports functions with a single input
argument. However, to access table elements, user must provide two
numbers, i.e. the number of table and the index of element. So, in
order to allow to access a table element with a function, a previous
preparation step should be done.
There are 16 different opcodes whose name is associated with a number
from 0 to 15. User can associate a specific table with each opcode (so
the maximum number of tables that can be accessed in function fashion
is 16). Prior to access a table, user must associate the table with
one of the 16 opcodes by means of an opcode chosen among
tb0_init...tb15_init. For example,
tb0_init 1
associates table 1 with tb0( ) function, so that, each element of
table 1 can be accessed (in function fashion) with:
kvar = tb0(k_some_index_of_table1) * k_some_other_var
ivar = tb0(i_some_index_of_table1) + i_some_other_var
etc...
By using these opcodes, user can drastically reduce the number of
lines of an orchestra, improving its readability.
_________________________________________________________________
ktrig changed kvar1 [, kvar2,..., kvarN]
changed opcode outputs a trigger signal that informs when one (or
several ones) of its k-rate arguments has changed. Useful with
valuator widgets or MIDI controllers.
______________ END OF OPCODES BY GABRIEL MALDONADO ______________
=======================================================================
csb64enc [OPTIONS ... ] infile1 [ infile2 [ ... ]]
DESCRIPTION
-----------
This utility converts any number of files to Base64 encoded CSD tags
(CsFileB).
OPTIONS
-------
-w n set line width to n characters (default: 72)
-o fname output file name (default: stdout)
AUTHOR
------
Istvan Varga
Jan 2003
---------------------------------------------------------------------
makecsd [OPTIONS ... ] infile1 [ infile2 [ ... ]]
DESCRIPTION
-----------
Creates a CSD file from the specified input files. The first input
file that has a .orc extension (case is not significant) is put to
the <CsInstruments> section, and the first input file that has a
.sco extension becomes <CsScore>. Any remaining files are Base64
encoded and added as <CsFileB> tags. An empty <CsOptions> section is
always added.
Some text filtering is performed on the orchestra and score file:
* newlines are converted to the native format of the system on
which makecsd is being run.
* blank lines are removed from the beginning and end of files.
* any trailing whitespace is removed from the end of lines.
* optionally, tabs can be expanded to spaces with an user specified
tabstop size.
OPTIONS
-------
-t n expand tabs to spaces using tabstop size n
(default: disabled). This applies only to the orchestra
and score file.
-w n set Base64 line width to n (default: 72). Note: the
orchestra and score are not wrapped.
-o fname output file name (default: stdout)
EXAMPLE
-------
makecsd -t 6 -w 78 -o file.csd file.mid file.orc file.sco sample.aif
This creates a CSD from file.orc and file.sco (tabs are expanded to
spaces assuming a tabstop size of 6 characters), and file.mid and
sample.aif are added as <CsFileB> tags containing Base64 encoded data
with a line width of 78 characters. The output file is file.csd.
AUTHOR
------
Istvan Varga
Jan 2003
---------------------------------------------------------------------
cs [-OPTIONS] <name> [CSOUND OPTIONS ... ]
DESCRIPTION
-----------
Starts Csound with a set of options that can be controlled by
environment variables, and input and output files determined by the
specified filename stem.
OPTIONS
-------
-OPTIONS OPTIONS is a sequence of alphabetic characters that can
be used for selecting the Csound executable to be run, as
well as the command line flags (see below).
There is a default for the option 'r' (selects real-time
output), but it can be overridden.
<name> this is the filename stem for selecting input files; it
may contain a path. Files that have .csd, .orc, or .sco
extension are searched, and either a CSD or an orc/sco
pair that matches <name> the best are selected. MIDI
files with a .mid extension are also searched, and if one
that matches <name> at least as close as the CSD or
orc/sco pair, it is used with the -F flag.
(NOTE: the MIDI file is not used if any -M or -F flag
is specified by the user - new in version 4.24.0)
Unless there is any option (-n or -o) related to audio
output, an output file name with the appropriate extension
is automatically generated (based on the name of selected
input files and format options).
The output file is always written to the current
directory.
Note: file name extensions are not case sensitive.
[CSOUND OPTIONS ... ]
any number of additional options for Csound that are
simply copied to the final command line to be executed.
The command line that is executed is generated from four parts:
1. Csound executable (possibly with options). This is exactly one
of the following (the last one has the highest precedence):
* a built-in default
* the value of the CSOUND environment variable
* environment variables with a name in the format of CSOUND_x
where x is an uppercase letter selected by characters of
the -OPTIONS string. Thus, if the -dcba option is used,
and the environment variables CSOUND_B and CSOUND_C are
defined, the value of CSOUND_B will take effect.
2. Any number of option lists, added in the following order:
* either some built-in defaults, or the value of the
CSFLAGS environment variable if it is defined.
* environment variables with a name in the format of CSFLAGS_x
where x is an uppercase letter selected by characters of
the -OPTIONS string. Thus, if the -dcba option is used,
and the environment variables CSFLAGS_A and CSFLAGS_C are
defined as '-M 1 -o dac' and '-m231 -H0', respectively,
the string '-m231 -H0 -M 1 -o dac' will be added.
3. The explicit options of [CSOUND OPTIONS ... ].
4. Any options and file names generated from <name>.
Note: quoted options that contain spaces are allowed.
EXAMPLES
--------
Assuming the following environment variables:
CSOUND = csoundfltk.exe -W
CSOUND_D = csound64.exe -J
CSOUND_R = csoundfltk.exe -h
CSFLAGS = -d -m135 -H1 -s
CSFLAGS_D = -f
CSFLAGS_R = -m0 -H0 -o dac1 -M "MIDI Yoke NT: 1" -b 200 -B 6000
And a directory that contains:
foo.orc piano.csd
foo.sco piano.mid
im.csd piano2.mid
ImproSculpt2_share.csd foobar.csd
The following commands will execute as shown:
cs foo => csoundfltk.exe -W -d -m135 -H1 -s -o foo.wav \
foo.orc foo.sco
cs foob => csoundfltk.exe -W -d -m135 -H1 -s \
-o foobar.wav foobar.csd
cs -r imp -i adc => csoundfltk.exe -h -d -m135 -H1 -s -m0 -H0 \
-o dac1 -M "MIDI Yoke NT: 1" \
-b 200 -B 6000 -i adc \
ImproSculpt2_share.csd
cs -d im => csound64.exe -J -d -m135 -H1 -s -f -o im.sf \
im.csd
cs piano => csoundfltk.exe -W -d -m135 -H1 -s \
-F piano.mid -o piano.wav \
piano.csd
cs piano2 => csoundfltk.exe -W -d -m135 -H1 -s \
-F piano2.mid -o piano2.wav \
piano.csd
AUTHOR
------
Istvan Varga
Jan 2003
============== clockon / clockoff / readclock example ===============
<CsoundSynthesizer>
; clockon/clockoff/readclock example - written by Istvan Varga, 2003
; measures the approximate time it takes to execute any Csound
; orchestra code (perf time only), and calculates the maximum possible
; overlaps in real-time
<CsOptions>
; run in real-time (there is no audio output, though)
-d -m0 -H0 -s -h -o dac
</CsOptions>
<CsInstruments>
sr = 44100
ksmps = 30
nchnls = 1
instr 1
clockon 1
; ---- put here any code to be timed ----
a1 vco2 1000, 440
; ---- end of test code ----
clockoff 1
; dummy clockon/clockoff pair to measure the CPU usage of the
; timer itself
clockon 2
clockoff 2
; read the time values. readclock works at k-rate if it has a k-rate
; output variable. imode=1 (real time) is used, because it has higher
; time resolution (better than 1 us under Win32, and 1 CPU cycle
; under Linux/x86) than imode=0 (CPU time, usually ~1 ms resolution),
; although other programs running in multi-tasking may result in
; incorrect times being measured.
ktime readclock 1, 1
ktime2 readclock 2, 1
; subtract the time elapsed by the dummy clockon/clockoff pair for
; more a accurate result
vdecr ktime, ktime2
; attempt to filter out anomalous values
ktime2 limit ktime2, 0.000001, 1.0 ; 1 ns to 1 ms
; apply smoothing for stable output; however, it takes longer time
; (~10-20 seconds) to reach the final value
ktime2 port ktime, 1.0, 0.1
; estimate the maximum possible overlaps in real-time by dividing the
; time of a k-cycle with the measured time
kovrlp = (1000 / kr) / ktime2
; convert milliseconds to microseconds
vmul ktime2, 1000
; print the results
printks "time (us) = %f, max overlaps = %f\\n", 0.5, ktime2, kovrlp
endin
</CsInstruments>
<CsScore>
i 1 0 3600
e
</CsScore>
</CsoundSynthesizer>
=====================================================================
© Istvan Varga, 2002