Command-line Flags
Prev | The Csound Command | Next

## Command-line Flags

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

Listed first are the traditional flags present in Csound 4. Look further down for Csound 5 specific 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

-@ FILE

  Provide an extended command-line in file “FILE”

-3, --format=24bit

  Use 24-bit audio samples.

-8, --format=uchar

  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, --aiff, --format=aiff

  Write an AIFF format soundfile. Use with the -c, -s, -l, or -f flags.

-a, --format=alaw

  Use a-law audio samples.

-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. 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, --iobufsamps=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, --cscore

  Use Cscore processing of the scorefile.

-c, --format=schar

  Use 8-bit signed character audio samples.

-D, --defer-gen1

  Defer GEN01 soundfile loads until performance time.

-d, --nodisplays

  Suppress all displays.

--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, --midifile=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, --format=float

  Use single-format float audio samples (not playable on some systems, but can be read by -i, soundin and GEN01

-G, --postscriptdisplay

  Suppress graphics, use PostScript displays instead.

-g, --asciidisplay

  Suppress graphics, use ASCII displays instead.

-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.

-h, --noheader

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

--help

  Display on-line help message.

-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.

-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.

  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. 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.

-J, --ircam, --format=ircam

  Write an IRCAM format soundfile.

-j FILE

  Currently disabled. Use database FILE for messages to print to console during performance. In Csound 5.00 and later versions, the localization of messages is controlled by two environment variables, both of which are optional. CSSTRNGS points to a directory containing .xmg files, and CS_LANG selects a language.

-K, --nopeaks

  Do not generate any PEAK chunks.

-k NUM, --control-rate=NUM

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

-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.

-l, --format=long

  Use long integer audio samples.

-M DEVICE, --midi-device=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, --messagelevel=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

  - 32 = dB, no colors

  - 64 = dB, out of range highlighted with red

  - 96 = dB, all colors

  The default is 135 (128+4+2+1), which means all messages, raw amplitude values, and printing elapsed time at the end of performance.

--midioutfile=FILENAME

  Save MIDI output to a file (Csound 5.00 and later only).

-N, --notify

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

-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.

-O FILE, --logfile=FILE

  Log output to file FILE.

-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, 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 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. 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.

-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, --rewrite

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

-r NUM, --sample-rate=NUM

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

-s, --format=short

  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 for Csound 5.00 and later.

--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).

-T, --terminate-on-midi

  Terminate the performance when the end of MIDI file is reached.

-t0, --keep-sorted-score

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

-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. WARNING: this mode of operation is experimental and may be unreliable.

-U UTILITY, --utility=UTILITY

  Invoke the utility program UTILITY. Use any invalid name to list the available utilities.

-u, --format=ulaw

  Use u-law audio samples.

-v, --verbose

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

-W, --wave, --format=wave

  Write a WAV format soundfile.

-x FILE, --extract-score=FILE

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

-Z, --dither

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

-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> <outargs> <inargs>

Csound5 Command-line Flags

--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).

--displays

  Enables displays, reverting the effect of any previous -d flag.

--no-expression-opt

  Disables expression optimization.

-+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)

-+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.

-+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).

-+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).

-+skip_seconds=float

  (min: 0) Start playback at the specified time (in seconds), skipping earlier events in the score and MIDI file.

--omacro:XXX=YYY

  Set orchestra macro XXX to value YYY

--smacro:XXX=YYY

  Set score macro XXX to value YYY

--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.

Prev | Up | Next
Description | Home | Unified File Format for Orchestras and Scores