     CSOUND(1Csound)                                             CSOUND(1Csound)
                                     7 Feb 1991

     NAME
          Csound - digital audio processing and sound synthesis

     SYNOPSIS
               csound [flags] orchfile scorefile

     OVERVIEW
          Csound is an environment in which a "scorefile" or external event
          sequence can invoke arbitrarily complex signal-processing
          "instruments" to produce sound.  Audio may be displayed during its
          creation, and the resulting sound sent to an on-line audio device or
          to an intermediate soundfile for later playback.  Csound is invoked by
          a single command, which induces three phases of action:
             Score sorting
             Orchestra translation and loading
             Sound generation (audio processing and synthesis).

          Csound audio processing is supported by various score manipulation
          languages (SCOT, CSCORE, SCSORT, EXTRACT) and by soundfile analysis-
          synthesis methods including additive synthesis (ADSYN), linear
          predictive coding (LPC), and phase vocoding (PVOC).

          There is no complete on-line manual, but man entries exist for the
          stand-alone analysis and scoring programs.  More complete information
          can be found in the troff-able Csound Reference Manual, which provides
          an overview, tutorial, details of behavior, and step-by-step examples.

     DESCRIPTION
          csound is a command for passing an orchestra file and score file to
          the Csound environment to generate a soundfile.  In the above
          SYNOPSIS, all flag arguments are optional with set defaults.  Flags
          may appear either separately or bundled;  those that take an argument
          will expect to find it either immediately following or as the next
          argument.  Recognized flags are:

          -I       Init-time processing only.  Allocate and initialize all
                   instrument events as per the score, but skip all
                   Performance-time processing (no k-signals or a-signals, thus
                   no amplitudes and no sound).  Provides a fast validity check
                   of all score pfields and instrument i-variables.  Implies -n.

          -n       No sound output, i.e. do all sound generation, but bypass
                   audio output.  This flag will override a -o flag.

          -i sfnam Input soundfile name or audio-device name.  If this flag is
                   present, sound will be continuously read from the named file
                   or device, and will be available to all instruments
                   containing an "in" unit.  If no explicit path is given, the
                   file will be sought in the user's sound directory
                   (environment variable SFDIR); if sfnam is of the form
                   path/name, the file will be sought in the 'path' directory.

                                        - 1 -       Formatted:  December 8, 1999

     CSOUND(1Csound)                                             CSOUND(1Csound)
                                     7 Feb 1991

                   If sfnam is of the form /dev/name or stdin, sound will be
                   read from there.   The encoding format of an audio input file
                   is self-defining, described by its soundfile header;  if no
                   header is present, the format is presumed the same as the
                   generated output.  The channel count and sampling rate of an
                   audio input file must match that of the receiving Orchestra.

          -o sfnam Output soundfile name or audio-device name; the default name
                   is "test".  Csound writes continuously to a soundfile or
                   device, unless prevented by a -n flag.  If sfnam is omitted
                   or contains no explicit path, sound will be written to the
                   user's soundfile directory (environment variable SFDIR); if
                   sfnam is of the form path/name, sound will be placed in the
                   'path' directory.  If sfnam is of the form /dev/name or
                   stdout, sound will be sent there.

          -b N     Blocksize, in samples (not bytes), for the above sound I/O.
                   Typically 512 samples per buffer.  A larger number is more
                   efficient, but small numbers reduce the delay in realtime
                   performances.

          -h       Do not write a soundfile header in the sound output stream.

          -c       Write 8-bit signed-character sound samples.

          -a       Write 8-bit alaw-encoded sound samples.

          -u       Write 8-bit ulaw-encoded sound samples.

          -s       Write 16-bit short_integer sound samples.

          -l       Write 32-bit long_integer sound samples.

          -f       Write single-precision floating-point sound samples.  A float
                   file cannot generally be played, but can be rescaled, or read
                   by soundin and GEN01.

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

          -m N     Message level for standard (terminal) output.  Takes the sum
                   of 3 print control flags, turned on by the following values:
                   1 = note amplitude messages,  2 = samples out of range
                   message, 4 = warning messages.  The default value is m7 (all
                   messages on).

          -d       Suppress all display functions.

                                        - 2 -       Formatted:  December 8, 1999

     CSOUND(1Csound)                                             CSOUND(1Csound)
                                     7 Feb 1991

          -g       Suppress graphics, and use ascii displays instead.  If the
                   user terminal supports graphic windows, display functions
                   ordinarily appear in that form.  This flag will invoke an
                   alternate system, printing graphs in ascii characters--as
                   would occur if the terminal did not support graphics.

          -S sname Interpret sname as a Scot scorefile, create a standard score
                   file from it, then perform the result.

          -x xname Extract a portion of the sorted scorefile (or 'score.srt')
                   according to the contents of xname (see Extract below).

          -B       Beat mode.  Use the uninterpreted Beats of score.srt for this
                   performance.  In this mode, the beat rate of score
                   performance is controllable from within the orchestra by a
                   tempo unit.

          -R indev Allow Realtime Line-oriented ascii-defined events via device
                   indev to activate instruments of the Orchestra.  E.g., the
                   name stdin would enable an associated realtime process to
                   initiate fully-specified score events through a pipe.  The
                   format of events is identical to that in an unsorted
                   scorefile, except that pfield 3 (duration) is given in
                   seconds and pfield 2 (start-time) is automatically set at
                   event-time.  A parallel score is optional.

          -M indev Allow MIDI invocation of the orchestra instruments via device
                   indev, of the form /dev/midi or stdin.  A parallel score is
                   optional.

          The orchfile is a collection of Instruments which are sequences of
          Csound statements invoking control-signal and audio-signal processing
          modules.  A simple instrument might appear as follows:

                    instr     3
               k1   linseg    p4, p3, p4/10
               a1   oscil     k1, p5, 1
                    out       a1
                    endin

          The scorefile is a collection of statements that create stored
          waveforms or activate orchestra instruments at some specified time.  A
          score statement contains parameter values that are passed to the
          instrument.  The following would create a single stored waveform, then
          invoke the above instrument to generate two two-beat audio events,
          with p4 amplitude 1000 and p5 pitches 440 and 522 Hertz:

               f 1  0    256  10   1
               i 3  0    2    1000 440
               i 3  2    2    1000 522

                                        - 3 -       Formatted:  December 8, 1999

     CSOUND(1Csound)                                             CSOUND(1Csound)
                                     7 Feb 1991

               e

          The Extract feature:

          This feature will extract a segment of a sorted numeric score file
          according to instructions taken from a control file.  The control file
          contains an instrument list and two time points, from and to, in the
          form:
             instruments 1 2   from 1:27.5    to 2:2

          The component labels may be abbreviated as i, f and t. The time points
          denote the begininng and end of the extract in terms of:
             [section no.] : [beat no.].
          Each of the three parts is also optional.  The default values for
          missing i, f or t are:
             all instruments,   begining of score,   end of score.

          extract reads an orchestra-readable score file and produces an
          orchestra-readable result.  Comments, tabs and extra spaces are
          flushed, w and a statements are added and an f0 reflecting the extract
          length is appended to the output.  Following an extract process, the
          abbreviated score will contain all function table statements, together
          with just those note statements that occur in the from-to interval
          specified.  Notes lying completely in the interval will be unmodified;
          notes that lie only partly within will their p3 durations truncated as
          necessary.

          Independent Preprocessing:

          Although the result of all score preprocessing is retained in the file
          score.srt after orchestra performance (it exists as soon as score
          preprocessing has completed), the user may sometimes want to run these
          phases independently.  The command
             scot  filename
          will process the Scot formatted filename, and leave a standard numeric
          score result in a file named score for perusal or later processing.

          The command
             scscort < infile   > outfile
          will put a numeric score infile through Carry, Tempo, and Sort
          preprocessing, leaving the result in outfile.

          Likewise extract, also normally invoked as part of the perf command,
          can be invoked as a standalone program:
             extract xfile < score.sort  > score.extract
          This command expects an already sorted score.  An unsorted score
          should first be sent through scsort then piped to the extract program:
             scsort < scorefile | extract xfile > score.extract

                                        - 4 -       Formatted:  December 8, 1999

     CSOUND(1Csound)                                             CSOUND(1Csound)
                                     7 Feb 1991

     SEE ALSO
          hetro(1Csound), lpcanal(1Csound), pvanal(1Csound), The Csound
          Reference Manual

     AUTHOR
          Written by Barry Vercoe, Music and Cognition group of the Media
          Laboratory at MIT.

                                        - 5 -       Formatted:  December 8, 1999