csound - Csound command.
The csound command executes Csound.
csound [flags] [orchname] [scorename]
csound [flags] [csdfilename]
Listed below are the command line flags available in Csound5 in
alphabetical order. Various platform implementations may not react the
same way to different flags! You can view the command line flags
organized by category in Command-line Flags (by Category).
The command line arguments are of 2 types: flags arguments (beginning
with a “-”,“--” or “-+”), and name arguments (such as filenames).
Certain flag arguments take a following name or numeric argument. Flags
that start with “--” and “-+” usually take an argument themselves using
“=”.
Command-line Flags
-@ FILE.
Provide an extended command-line in file “FILE”
-3.
Use 24-bit audio samples.
-8.
Use 8-bit unsigned character audio samples.
--format=type.
Set the audio file output format to one of the formats available in
libsndfile. At present the list is aiff, au, avr, caf, flac, htk,
ircam, mat4, mat5, nis, paf, pvf, raw, sd2, sds, svx, voc, w64,
wav, wavex and xi. Can also be used as --format=type:format or
--format=format:type to set both the file type (wav, aiff, etc.)
and sample format (short, long, float, etc.) at the same time.
-A.
Write an AIFF format soundfile. Use with the -c, -s, -l, or -f
flags.
-a.
Use a-law audio samples.
-B 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. In
the case of portaudio output (the default real-time output), the -B
parameter (more precisely, -B / sr) is passed as the "suggested
latency" value. Other than that, Csound has no control over how
PortAudio interprets the parameter. The default is 1024 on Linux,
4096 on Mac OS X and 16384 on Windows.
-b NUM.
Number of audio sample-frames per sound i/o software buffer. Large
is efficient, but small will reduce audio I/O delay and improve the
accuracy of the timing of real time events. The default is 256 on
Linux, 1024 on MacOS X, and 4096 on Windows. 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 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.
Note: if both -iadc and -odac are used at the same time (full
duplex real time audio), the -b option should be set to an integer
multiple of ksmps.
-C.
Use Cscore processing of the scorefile.
-c.
Use 8-bit signed character audio samples.
--csd-line-nums=NUM.
Determines how line numbers are counted and displayed for error
messages when processing a Csound Unified Document file (.csd).
This flag has no effect if separate orchestra and score files are
used. (Csound 5.08 and later).
· 0 = line numbers are relative to the beginning of the orchestra
or score sections of the CSD
· 1 = line numbers are relative to the beginning of the CSD file.
This is the default as of Csound 5.08.
-D.
Defer GEN01 soundfile loads until performance time.
-d.
Suppress all displays.
--displays.
Enables displays, reverting the effect of any previous -d flag.
--default-paths.
Reenables adding of directory of CSD/ORC/SCO to search paths,
if it has been disabled by a previous --no-default-paths (e.g.
in .csoundrc).
--env:NAME=VALUE.
Set environment variable NAME to VALUE. Note: not all
environment variables can be set this way, because some are
read before parsing the command line. INCDIR, SADIR, SFDIR, and
SSDIR are known to work.
--env:NAME+=VALUE.
Append VALUE to ´;´ separated list of search paths in
environment variable NAME (should be INCDIR, SADIR, SFDIR, or
SSDIR). If a file is found in multiple directories, the last
will be used.
--expression-opt.
Since Csound 5. 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.
Warning
When --expression-opt is turned on, it is not
allowed to use the i() function with an expression
argument, and relying on the value of k-rate
expressions at i-time is unsafe.
-F FILE.
Read MIDI events from MIDI file FILE. The file should
have only one track in Csound versions 4.xx and
earlier; this limitation is removed in Csound 5.00.
-f.
Use single-format float audio samples (not playable on
some systems, but can be read by -i, soundin and GEN01
-G.
Suppress graphics, use PostScript displays instead.
-g.
Suppress graphics, use ASCII displays instead.
-H#.
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.
-h.
No header on output soundfile. Don´t write a file
header, just binary samples.
--help.
Display on-line help message.
-I.
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. This option is exclusive of the
--syntax-check-only flag.
-i 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.
The name devaudio or adc will request sound from
the host audio input device. It is possible to
select a device number by appending an integer
value in the range 0 to 1023, or a device name
separated by a : character (e.g. -iadc3,
-iadc:hw:1,1). It depends on the host audio
interface whether a device number or a name should
be used. In the first case, an out of range number
usually results in an error and listing the valid
device numbers.
-+id_artist=string.
(max. length = 200 characters) Artist tag in output
soundfile (no spaces)
-+id_comment=string.
(max. length = 200 characters) Comment tag in
output soundfile (no spaces)
-+id_copyright=string.
(max. length = 200 characters) Copyright tag in
output soundfile (no spaces)
-+id_date=string.
(max. length = 200 characters) Date tag in output
soundfile (no spaces)
-+id_software=string.
(max. length = 200 characters) Software tag in
output soundfile (no spaces)
-+id_title=string.
(max. length = 200 characters) Title tag in output
soundfile (no spaces)
-+ignore_csopts=integer.
If set to 1, Csound will ignore all options
specified in the csd file´s CsOptions section. See
Unified File Format for Orchestras and Scores.
-+input_stream=string.
Pulseaudio input stream name.
-J.
Write an IRCAM format soundfile.
-+jack_client=[client_name].
The client name used by Csound, defaults to
´csound5´. If multiple instances of Csound connect
to the JACK server, different client names need to
be used to avoid name conflicts. (Linux and Mac OS
X only)
-+jack_inportname=[input port name prefix],
-+jack_outportname=[output port name prefix] .
Name prefix of Csound JACK input/output ports; the
default is ´input´ and ´output´. The actual port
name is the channel number appended to the name
prefix. (Linux and Mac OS X only)
Example: with the above default settings, a stereo
orchestra will create these ports in full duplex
operation:
csound5:input1 (record left)
csound5:input2 (record right)
csound5:output1 (playback left)
csound5:output2 (playback right)
-K.
Do not generate any PEAK chunks.
-k NUM.
Override the control rate (KR) supplied by the
orchestra.
-L 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.
-l.
Use long integer audio samples.
-M DEVICE.
Read MIDI events from device DEVICE. If using ALSA
MIDI (-+rtmidi=alsa), devices are selected by name
and not number. So, you need to use an option like
-M hw:CARD,DEVICE where CARD and DEVICE are the
card and device numbers (e.g. -M hw:1,0). In the
case of PortMidi and MME, DEVICE should be a
number, and if it is out of range, an error occurs
and the valid device numbers are printed.
-m NUM.
Message level for standard (terminal) output. Takes
the sum of any of the following values:
· 1 = note amplitude messages
· 2 = samples out of range message
· 4 = warning messages
· 128 = print benchmark information
And exactly one of these to select note
amplitude format:
· 0 = raw amplitudes, no colours
· 32 = dB, no colors
· 64 = dB, out of range highlighted with red
· 96 = dB, all colors
· 256 = raw, out of range highlighted with
red
· 512 = raw, all colours
The default is 135 (128+4+2+1), which means
all messages, raw amplitude values, and
printing elapsed time at the end of
performance. The coloring of raw amplitudes
was introduced in version 5.04.
--m-amps=NUM.
Message level for amplitudes on standard
(terminal) output.
· 0 = no note amplitude messages
· 1 = note amplitude messages
--m-range=NUM.
Message level for out of range messages
on standard (terminal) output.
· 0 = no samples out of range message
· 1 = samples out of range message
--m-warnings=NUM.
Message level for warnings on
standard (terminal) output.
· 0 = no warning messages
· 1 = warning messages
--m-dB=NUM.
Message level for amplitude
format on standard (terminal)
output.
· 0 = absolute amplitude
messages
· 1 = dB amplitude messages
--m-colours=NUM.
Message level for amplitude
format on standard
(terminal) output.
· 0 = no colouring of
amplitude messages
· 1 = colouring of
amplitude messages
--m-benchmarks=NUM.
Message level for
benchmark information
on standard (terminal)
output.
· 0 = no benchnark
numbers
· 1 = print benchnark
numbers
-+max_str_len=integer.
(min: 10, max:
10000) Maximum
length of string
variables + 1;
defaults to 256
allowing a length
of 255 characters.
The length of
string constants is
not limited by this
parameter.
--midi-key=N.
Route MIDI note on
message key number
to pfield N as MIDI
value [0-127].
--midi-key-cps=N.
Route MIDI note on
message key number
to pfield N as
cycles per second.
--midi-key-oct=N.
Route MIDI note on
message key number
to pfield N as
linear octave.
--midi-key-pch=N.
Route MIDI note on
message key number
to pfield N as
oct.pch (pitch
class).
--midi-velocity=N.
Route MIDI note on
message velocity
number to pfield N
as MIDI value
[0-127].
--midi-velocity-amp=N.
Route MIDI note on
message velocity
number to pfield N
as amplitude
[0-0dbFS].
--midioutfile=FILENAME.
Save MIDI output to
a file (Csound 5.00
and later only).
-+msg_color=boolean.
Enable message
attributes (colors
etc.); might need
to be disabled on
some terminals
which print strange
characters instead
of modifying text
attributes.
default: true.
-+mute_tracks=string.
(max. length = 255
characters) Ignore
events (other than
tempo changes) in
MIDI file tracks
defined by pattern
(for example,
-+mute_tracks=00101
will mute the third
and fifth tracks).
-N.
Notify (ring the
bell) when score or
MIDI track is done.
-n.
No sound. Do all
processing, but
bypass writing of
sound to disk. This
flag does not
change the
execution in any
other way.
--no-default-paths.
Disables adding of
directory of
CSD/ORC/SCO to
search paths.
--no-expression-opt.
Disables expression
optimization.
-O FILE.
Log output to file
FILE. If FILE is
null (i.e. -O null
or --logfile=null)
all printing of
messages to the
console is
disabled.
-o 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,
while null results
in no sound output
similarly to the -n
flag. If no name is
given, the default
name will be test.
The name devaudio
or dac (you can use
-odac or -o dac)
will request
writing sound to
the host audio
output device. It
is possible to
select a device
number by appending
an integer value in
the range 0 to
1023, or a device
name separated by a
: character (e.g.
-odac3,
-odac:hw:1,1). It
depends on the host
audio interface
whether a device
number or a name
should be used. In
the first case, an
out of range number
usually results in
an error and
listing the valid
device numbers.
--omacro:XXX=YYY.
Set orchestra macro
XXX to value YYY
-+output_stream=string.
Pulseaudio output
stream name.
-Q DEVICE.
Enables MIDI OUT
operations to
device id DEVICE.
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 reduced by using
a lower value for
the -b flag.
If using ALSA MIDI
(-+rtmidi=alsa),
devices are
selected by name
and not number. So,
you need to use an
option like -Q
hw:CARD,DEVICE
where CARD and
DEVICE are the card
and device numbers
(e.g. -Q hw:1,0).
In the case of
PortMidi and MME,
DEVICE should be a
number, and if it
is out of range, an
error occurs and
the valid device
numbers are
printed.
-R.
Continually rewrite
the header while
writing the
soundfile
(WAV/AIFF).
-r NUM.
Override the
sampling rate (SR)
supplied by the
orchestra.
-+raw_controller_mode=boolean.
Disable special
handling of MIDI
controllers like
sustain pedal, all
notes off etc.,
allowing the use of
all the 128
controllers for any
purpose. This will
also set the
initial value of
all controllers to
zero. Default: no.
-+rtaudio=string.
(max. length = 20
characters) Real
time audio module
name. The default
is PortAudio. Also
available,
depending on
platform and build
options: Linux:
alsa, jack;
Windows: mme; Mac
OS X: CoreAudio. In
addition, null can
be used on all
platforms, to
disable the use of
any real time audio
plugin.
-+rtmidi=string.
(max. length = 20
characters) Real
time MIDI module
name. Defaults to
PortMidi, other
options (depending
on build options):
Linux: alsa;
Windows: mme,
winmm. In addition,
null can be used on
all platforms, to
disable the use of
any real time MIDI
plugin.
ALSA MIDI devices
are selected by
name and not
number. So, you
need to use an
option like -M
hw:CARD,DEVICE
where CARD and
DEVICE are the card
and device numbers
(e.g. -M hw:1,0).
-s.
Use short integer
audio samples.
--sched.
Linux only. Use
real-time
scheduling and lock
memory. (Also
requires -d and
either -o dac or -o
devaudio). See also
--sched=N below.
--sched=N.
Linux only. Same
as --sched, but
allows specifying a
priority value: if
N is positive (in
the range 1 to 99)
the scheduling
policy SCHED_RR
will be used with a
priority of N;
otherwise,
SCHED_OTHER is used
with the nice level
set to N. Can also
be used in the
format
--sched=N,MAXCPU,TIME
to enable the use
of a "watchdog"
thread that
terminates Csound
if the average CPU
usage exceeds
MAXCPU percents
over a peroid of
TIME seconds (new
in Csound 5.00).
-+server=string.
Pulseaudio server
name.
-+skip_seconds=float.
(min: 0) Start
playback at the
specified time (in
seconds), skipping
earlier events in
the score and MIDI
file.
--smacro:XXX=YYY.
Set score macro XXX
to value YYY
--strset.
Csound 5. The
--strset option
allows setting
strset string
values from the
command line, in
the format
´--strsetN=VALUE´.
It is useful for
passing parameters
to the orchestra
(e.g. file names).
--syntax-check-only.
Causes Csound to
exit immediately
after the orchestra
and score parsers
finish checking the
syntax of the input
files and before
the orchestra
performs the score.
This option is
exclusive of the
--i-only flag.
(Csound 5.08 and
later).
-T.
Terminate the
performance when
the end of MIDI
file is reached.
-t0.
Prevents Csound
from deleting the
sorted score file,
score.srt, upon
exit.
-t 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. WARNING:
this mode of
operation is
experimental and
may be unreliable.
-U UTILITY.
Invoke the utility
program UTILITY.
Use any invalid
name to list the
available
utilities.
-u.
Use u-law audio
samples.
-v.
Verbose translate
and run. Prints
details of orch
translation and
performance,
enabling errors to
be more clearly
located.
-W.
Write a WAV format
soundfile.
-x FILE.
Extract a portion
of the sorted
score, score.srt,
using the extract
file FILE (see
Extract).
-Z.
Switch on dithering
of audio conversion
from internal
floating point to
32, 16 and 8-bit
formats. The
default form of the
dither is
triangular.
-Z.
Switch on dithering
of audio conversion
from internal
floating point to
32, 16 and 8-bit
formats. In the
case of -Z the next
digit should be a 1
(for trangular) or
a 2 (for uniform).
The exact
interpretation
depends on the
output system.
-z NUM.
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>
<outargs>
<inargs>
Barry Vercoe
MIT Media Lab
Author.
Copyright © 1986, 1992 Massachusetts Institute of Technology