Man Linux: Main Page and Category List

NAME

       csound - Csound command.

DESCRIPTION

       The csound command executes Csound.

SYNTAX

           csound  [flags]  [orchname]  [scorename]

           csound  [flags]  [csdfilename]

CSOUND COMMAND LINE FLAGS

       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>

AUTHOR

       Barry Vercoe
       MIT Media Lab

           Author.

COPYRIGHT

       Copyright © 1986, 1992 Massachusetts Institute of Technology