<!-- Converted to DocBook/SGML by Kevin Conder -->
<section id="CommandUnifile">
  <title>Unified File Format for Orchestras and Scores</title>
   
  <section>
    <title>Description</title>
      <para>
        The Unified File Format <indexterm id="IndexUnifiedFile"><primary>Unified File Format</primary></indexterm>, introduced in Csound version 3.50, enables the orchestra and score files, as well as command line flags, to be combined in one file. The file has the extension <emphasis>.csd</emphasis>. This format was originally introduced by Michael Gogins in AXCsound.

	<indexterm id="IndexCSD"><primary>.csd</primary></indexterm>
	<indexterm id="IndexCsoundrcUnifile"><primary>.csoundrc</primary></indexterm>
	<indexterm id="IndexCsInstruments"><primary>&lt;CsInstruments&gt;</primary></indexterm>
	<indexterm id="IndexCsMidifileB"><primary>&lt;CsMidifileB&gt;</primary></indexterm>
	<indexterm id="IndexCsOptions"><primary>&lt;CsOptions&gt;</primary></indexterm>
	<indexterm id="IndexCsSampleB"><primary>&lt;CsSampleB&gt;</primary></indexterm>
	<indexterm id="IndexCsScore"><primary>&lt;CsScore&gt;</primary></indexterm>
	<indexterm id="IndexCsoundSynthesizer"><primary>&lt;CsoundSynthesizer&gt;</primary></indexterm>
	<indexterm id="IndexCsVersion"><primary>&lt;CsVersion&gt;</primary></indexterm>
      </para>

      <para>
        The file is a structured data file which uses markup language, similar to any SGML such as HTML. Start tags (&lt;<emphasis>tag</emphasis>&gt;) and end tags (&lt;/<emphasis>tag</emphasis>&gt;) are used to delimit the various elements. The file is saved as a text file.
      </para>
  </section>

  <section>
    <title>Structured Data File Format</title>

    <section>
      <title>Mandatory Elements</title>
      <para>
        The Csound Element is used to alert the csound compiler to the <emphasis>.csd</emphasis> format. The file must begin with the start tag <emphasis>&lt;CsoundSynthesizer&gt;. </emphasis>The last line of the file must be the end tag <emphasis>&lt;/CsoundSynthesizer&gt;.</emphasis> The remaining elements are defined below.
      </para>

      <section>
        <title>Options</title>
	<para>
          Csound command line flags are put in the Options Element. This section is delimited by the start tag <emphasis>&lt;CsOptions&gt;</emphasis> and the end tag <emphasis>&lt;/CsOptions&gt; </emphasis>Lines beginning with <emphasis>#</emphasis> or <emphasis>;</emphasis> are treated as comments.
	</para>
      </section>

      <section>
        <title>Instruments (Orchestra)</title>
	<para>
          The instrument definitions (orchestra) are put into the Instruments Element. The statements and syntax in this section are identical to the Csound orchestra file, and have the same requirements, including the header statements (<emphasis>sr</emphasis>, <emphasis>kr</emphasis>, etc.) This Instruments Element is delimited with the start tag <emphasis>&lt;CsInstruments&gt;</emphasis> and the end tag <emphasis>&lt;/CsInstruments&gt;.</emphasis>
	</para>
      </section>

      <section>
        <title>Score</title>
	<para>
          Csound score statements are put in the Score Element. The statements and syntax in this section are identical to the Csound score file, and have the same requirements. The Score Element is delimited by the start tag <emphasis>&lt;CsScore&gt; </emphasis>and the end tag <emphasis>&lt;/CsScore&gt;.</emphasis>
	</para>
      </section>
    </section>

    <section>
      <title>Optional Elements</title>

      <section>
        <title>Included Base64 Files</title>
        <para>
          Base64 encoded MIDI files may be included with the tag <emphasis>&lt;CsMidifileB filename=</emphasis><emphasis>filename</emphasis><emphasis>&gt;</emphasis>, where <emphasis>filename</emphasis> is the name of the file containing the MIDI information. There is no matching end tag. New in Csound version 4.07.
        </para>

        <para>
          Base64 encoded sample files may be included with the tag <emphasis>&lt;CsSampleB filename=</emphasis><emphasis>filename</emphasis><emphasis>&gt;</emphasis>, where <emphasis>filename</emphasis> is the name of the file containing the sample. There is no matching end tag. New in Csound version 4.07.
        </para>
      </section>

      <section>
        <title>Version Blocking</title>
        <para>
          Versions of Csound may blocked by placing one of the following statements between the start tag &lt;CsVersion&gt; and the end tag &lt;/CsVersion&gt;:

          <informalexample>
            <programlisting>
Before #.#
            </programlisting>
          </informalexample>

         or

          <informalexample>
            <programlisting>
After #.#
            </programlisting>
          </informalexample>

         where #.# is the requested Csound version number. The second statement may be written simply as:

          <informalexample>
            <programlisting>
#.#
            </programlisting>
          </informalexample>

         See example below. New in Csound version 4.09.
        </para>
      </section>

      <section>
        <title>Example</title>
	<para>
          Below is a sample file, test.csd, which renders a .wav file at 44.1 kHz sample rate containing one second of a 1 kHz sine wave. Displays are suppressed. test.csd was created from two files, tone.orc and tone.sco, with the addition of command line flags.

          <informalexample>
            <programlisting>
<emphasis>&lt;CsoundSynthesizer&gt;</emphasis>;
  ; test.csd - a Csound structured data file
  
<emphasis>&lt;CsOptions&gt;</emphasis>
  -W -d -o tone.wav 
<emphasis>&lt;/CsOptions&gt;</emphasis>
  
<emphasis>&lt;CsVersion&gt;</emphasis>    ;optional section
  Before 4.10  ;these two statements check for
  After 4.08   ;   Csound version 4.09
<emphasis>&lt;/CsVersion&gt;</emphasis>
  
<emphasis>&lt;CsInstruments&gt;</emphasis>
  ; originally tone.orc 
  <emphasis>sr</emphasis> = 44100
  <emphasis>kr</emphasis> = 4410
  <emphasis>ksmps</emphasis> = 10
  <emphasis>nchnls</emphasis> = 1
  <emphasis>instr</emphasis>   1 
      a1 <emphasis>oscil</emphasis> p4, p5, 1 ; simple oscillator 
         <emphasis>out</emphasis> a1
    <emphasis>endin</emphasis>
<emphasis>&lt;/CsInstruments&gt;</emphasis>

<emphasis>&lt;CsScore&gt;</emphasis>
  ; originally tone.sco
  f1 0 8192 10 1
  i1 0 1 20000 1000 ;play one second of one kHz tone
  e
<emphasis>&lt;/CsScore&gt;</emphasis>

<emphasis>&lt;/CsoundSynthesizer&gt;</emphasis>
            </programlisting>
          </informalexample>
	</para>
      </section>
    </section>
  </section>

  <section>
    <title>Command Line Parameter File</title>
    <para>
      If the file <emphasis>.csoundrc</emphasis> exists, it will be used to set the command line parameters. These can be overridden. It uses the same form as a <emphasis>.csd</emphasis> file. Lines beginning with <emphasis>#</emphasis> or <emphasis>;</emphasis> are treated as comments.
    </para>
  </section>
</section>
