Command Line FlagsCsound command linecsoundDescription
The csound command executes Csound.
SyntaxcsoundorchnamescorenamecsoundcsdfilenameCsound command line flags
Listed below are the command line flags available in Csound6 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-3, --format=24bit--format=24bit
Use 24-bit audio samples.
-8-8, --format=uchar--format=uchar
Use 8-bit unsigned character audio samples.
--format=type--format
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, MPC,
nist, ogg, paf, pvf, raw, sd2, sds, svx, voc, w64, W64,
wav, wavex, WVE, 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-A, --aiff--aiff, --format=aiff--format=aiff
Write an AIFF format soundfile. Use with the -c, -s, -l, or -f flags.
-a-a, --format=alaw--format=alaw
Use a-law audio samples.
--aft-zero--aft-zero>
Use zero as initial value of after-touch.
-B NUM-B, --hardwarebufsamps=NUM--hardwarebufsamps
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-b, --iobufsamps=NUM--iobufsamps
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-C, --cscore--cscore
Use Cscore processing of the scorefile.
-c-c, --format=schar--format=schar
Use 8-bit signed character audio samples.
--csd-line-nums=NUM--csd-line-nums
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 CSD1 = line numbers are relative to the beginning of the CSD file. This is the default as of Csound 5.08.-D-D, --defer-gen1--defer-gen1
Defer GEN01 soundfile loads until performance time.
-d-d, --nodisplays--nodisplays
Suppress all displays. See -O
if you want to save the log to a file. This option
only works from the command line and not from .csound6rc or
a CsOptions section of a csd file. It needs to be acted
upon before sound proper starts. It is ignored in .csound6rc
and CsOptions.-d--daemon
Run in daemon mode: do not exit if CSD/orchestra is not given, is empty or does not compile.
--devices[=x]--devices
list audio devices (x=out, output devices only; x=in,
input; else input and output) and exit.
--displays--displays
Enables displays, reverting the effect of any previous -d flag.
--default-paths--no-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 .csound6rc).
--env:NAME=VALUE--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--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--expression-optNote that this option has no affect in
csound6.In Csound 5 only.
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 namesindex 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-F, --midifile=FILE--midifile
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-f, --format=float--format=float
Use single-format float audio samples (not playable on some systems, but can be read by -i, soundin and GEN01-G-G, --postscriptdisplay--postscriptdisplay
Suppress graphics, use PostScript displays instead.
-g-g, --asciidisplay--asciidisplay
Suppress graphics, use ASCII displays instead.
--get-system-sr--get-system-sr
prints system sr and exits, requires previous -o dac.
If the audio does not support this request then -1 is reported.
-H#-H, --heartbeat=NUM--heartbeat
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-h, --noheader--noheader
No header on output soundfile.
Don't write a file header, just binary samples.
--help--help
Display on-line help message.
-I-I, --i-only--i-onlyi-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-i, --input=FILE--input
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.
The audio coming in using -i can be received using opcodes like inch.
-+id_artist=string-+id_artist
(max. length = 200 characters) Artist tag in output soundfile (no spaces)
-+id_comment=string-+id_comment
(max. length = 200 characters) Comment tag in output soundfile (no spaces)
-+id_copyright=string-+id_copyright
(max. length = 200 characters) Copyright tag in output soundfile (no spaces)
-+id_scopyright=integer-+id_scopyright
(Since version 6.05) Simple copyright/licence encoded as
an integer. Coding is:
0: "All rights reserved" (default)1: "Creative Commons Attribution-NonCommercial-NoDerivatives (CC BY-NC-ND)"2: "Creative Commons Attribution-NonCommercial-ShareAlike (CC BY-NC-SA)"3: "Creative Commons Attribution-NonCommercial (CC BY-NC)"4: "Creative Commons Attribution-NoDerivatives (CC BY-ND)"5: "Creative Commons Attribution-ShareAlike (CC BY-SA)"6: "Creative Commons Attribution-ShareAlike (CC BY)"7: "Licenced under BSD"-+id_date=string-+id_date.
(max. length = 200 characters) Date tag in output soundfile (no spaces)
-+id_software=string-+id_software
(max. length = 200 characters) Software tag in output soundfile (no spaces)
-+id_title=string-+id_title
(max. length = 200 characters) Title tag in output soundfile (no spaces)
-+ignore_csopts=integer-+ignore_csopts=
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-+input_stream
Pulseaudio input stream name.
-J-J, --ircam--ircam, --format=ircam--format=ircam
Write an IRCAM format soundfile.
-j NUM-j NUM
Make NUM processes available for
rendering. This is only advantageous if the number of
processors on the computer is the same or more that the number
of requested processes. It also may slow rendering
down if ksmps is too small.
-+jack_client=[client_name]-+jack_client
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]
-+jack_inportname-+jack_outportname
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-K, --nopeaks--nopeaks
Do not generate any PEAK chunks.
-k NUM-k, --control-rate=NUM--control-rate
Override the control rate (KR) supplied by the orchestra.
-L DEVICE-L, --score-in=DEVICE--score-in
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.
The -L flag is only valid on *NIX systems which have pipes. It doesn't work on Windows.
-l-l, --format=long--format=long
Use long integer audio samples.
-M DEVICE-M, --midi-device=DEVICE--midi-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.When using PortMidi, you can use '-Ma' to enable all devices. This is also convenient when you don't have devices as it will not generate an error.
-m NUM-m, --messagelevel=NUM--messagelevel
Message level for standard (terminal) output. Takes the sum of any of the following values:
1 = note amplitude messages2 = samples out of range message4 = warning messages128 = print benchmark information
And exactly one of these to select note amplitude format:
0 = raw amplitudes, no colours32 = dB, no colors64 = dB, out of range highlighted with red96 = dB, all colors256 = raw, out of range highlighted with red512 = 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 messages1 = note amplitude messages--m-range=NUM
Message level for out of range messages on standard (terminal) output.
0 = no samples out of range message1 = samples out of range message--m-warnings=NUM
Message level for warnings on standard (terminal) output.
0 = no warning messages1 = warning messages--m-dB=NUM
Message level for amplitude format on standard (terminal) output.
0 = absolute amplitude messages1 = dB amplitude messages--m-colours=NUM
Message level for amplitude format on standard (terminal) output.
0 = no colouring of amplitude messages1 = colouring of amplitude messages--m-benchmarks=NUM
Message level for benchmark information on standard (terminal) output.
0 = no benchnark numbers1 = print benchnark numbers-+max_str_len=integer-+max_str_len
(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-devices[=x]--midi-devices
list midi devices (x=out, output devices only; x=in,
input; else input and output) and exit.
--midi-key=N--midi-key=N
Route MIDI note on message key number to pfield N as
MIDI value [0-127].
--midi-key-cps=N--midi-key-cps=N
Route MIDI note on message key number to pfield N
as cycles per second.
--midi-key-oct=N--midi-key-oct=N
Route MIDI note on message key number to pfield
N as linear octave.
--midi-key-pch=N--midi-key-pch=N
Route MIDI note on message key number to
pfield N as oct.pch (pitch class).
--midi-velocity=N--midi-velocity=N
Route MIDI note on message velocity number to pfield
N as MIDI value [0-127].
--midi-velocity-amp=N--midi-velocity-amp=N
Route MIDI note on message velocity number to pfield
N as amplitude [0-0dbFS].
--midioutfile=FILENAME--midioutfile
Save MIDI output to a file (Csound 5.00 and later only).
-+msg_color=boolean-+msg_color
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-+mute_tracks
(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-N, --notify--notify
Notify (ring the bell) when score or MIDI track is done.
-n-n, --nosound--nosound
No sound. Do all processing, but bypass writing of sound to disk. This flag does not change the execution in any other way.
--num-threads=NUM--num-thread=NUM
Make NUM processes available for
rendering. This is only advantageous if the number of
processors on the computer is more that the number
of requested processes. It also may slow rendering
down if ksmps is too small.
--no-default-paths--no-default-paths
Disables adding of directory of CSD/ORC/SCO to search paths.
--no-expression-opt--no-expression-opt
Disables expression optimization.
-O FILE-O, --logfile=FILE--logfile
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.
This option only works from the command line and
not from .csound6rc or a CsOptions section of a csd
file. It needs to be acted upon before sound proper
starts. It is ignored in .csound6rc and
CsOptions.-o FILE-o, --output=FILE--output
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.
--ogg--ogg
Set output file format to ogg. (csound 5.18 and later)
--omacro:XXX=YYY--omacro
Set orchestra macro XXX to value YYY
--opcode-lib=LIBNAME--opcode-lib
Load plugin library LIBNAME.
--orc orcname--orc
Set the argument as the orchestrra file. Used when not
score is required>. (Csound 5.18 and later).
--ksmps=N--ksmps
Set ksmps override to N (6.05 and later).
-+output_stream=string-+output_stream
Pulseaudio output stream name.
--port=N--port
Set UDP port on which to listen for commands and instruments/orchestra code
(implies --daemon)
--udp-echo--udp-echo
Switches on printing of UDP commands on the terminal. Any
messages received by the UDP server are echoed (whether
they are valid commands or not).
--udp-console=address:port--udp-console
Redirects the console messages to a remote address:port
via UDP.
--udp-mirror-console=address:port--udp-mirror-console
Mirrors the console messages to a remote address:port
via UDP.
-Q DEVICE-Q
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-R, --rewrite--rewrite
Continually rewrite the header while writing the soundfile (WAV/AIFF).
-r NUM-r, --sample-rate=NUM--sample-rate
Override the sampling rate (SR) supplied by the orchestra.
-+raw_controller_mode=boolean-+raw_controller_mode
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.
--realtime--realtime
realtime priority mode is switched on which the following effects:
all opcode audio file reading/writing is handled asynchronously
by a separate thread.all init-pass operations are also performed asynchronously.-+rtaudio=string-+rtaudio
(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-+rtmidi
(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-s, --format=short--format=short
Use short integer audio samples.
--sample-accurate--sample-accurate
Start and stop instances of instruments at the nearest
sample to the requested time. This is in contrast to
traditional Csound which rounds the times to the nearest
k-cycle. Note that this does not work with tied notes.
--sched--schedLinux 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--sched=NLinux 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-+server
Pulseaudio server name.
-+skip_seconds=float-+skip_seconds
(min: 0) Start playback at the specified time (in seconds),
skipping earlier events in the score and MIDI file.
--smacro:XXX=YYY--smacro
Set score macro XXX to value YYY
--strset--strsetCsound 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--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-T, --terminate-on-midi--terminate-on-midi
Terminate the performance when the end of MIDI file is reached.
-t0-t0, --keep-sorted-score--keep-sorted-score
Prevents Csound from deleting the sorted score file, score.srt, upon exit.
-t NUM-t, --tempo=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. WARNING: this mode of operation is experimental and may be unreliable.
-U UTILITY-U, --utility=UTILITY--utility
Invoke the utility program UTILITY. Use any
invalid name to list the available utilities.
-u-u,
--format=ulaw--format=ulaw
Use u-law audio samples.
--vbr-quality=X--vbr-quality=X
Set variable bit-rate quality for output to ogg. (Csound 6.03 and later).
-v-v, --verbose--verbose
Verbose translate and run. Prints details of orch translation and performance, enabling errors to be more clearly located.
--version--version
Exits after printing version information.
-W-W, --wave--wave, --format=wave--format=wave
Write a WAV format soundfile.
-x FILE-x, --extract-score=FILE--extract-score
Extract a portion of the sorted score, score.srt, using the extract file FILE (see Extract).
-Z-Z, --dither--dither
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-Zd, --dither--triangular--dither--triangular, --dither--uniform--dither--uniform
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-z, --list-opcodesNUM--list-opcodesNUM
List opcodes in this version:
no NUM, just show namesNUM = 0, just show namesNUM = 1, show arguments to each opcode using the format <opname> <outargs> <inargs>NUM = 2, show names including
deprecated onesNUM = 3, show arguments to each
opcode, including deprecated ones, using the format <opname> <outargs> <inargs>