path: root/command/unifile.xml

<section id="CommandUnifile">
  <title>Unified File Format for Orchestras and Scores</title>

  <section id="CommandUnifileDescription">
    <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>.csound6rc</primary></indexterm>
      <indexterm id="IndexCsFileB"><primary>&lt;CsFileB&gt;</primary></indexterm>
      <indexterm id="IndexCsFile"><primary>&lt;CsFile&gt;</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>
      <indexterm id="IndexCsLicense"><primary>&lt;CsLicense&gt;</primary></indexterm>
      <indexterm id="IndexCsShortLicense"><primary>&lt;CsShortLicense&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>

    <bridgehead>Structured Data File Format</bridgehead>
    <bridgehead>Mandatory Elements</bridgehead>
    <para>
      The first tag in the file must be the start tag <emphasis>&lt;CsoundSynthesizer&gt;. </emphasis>The last tag in the file must be the end tag <emphasis>&lt;/CsoundSynthesizer&gt;. </emphasis>This element is used to alert the csound compiler to the <emphasis>.csd</emphasis> format.  All text before the start tag and after the end tag is ignored by Csound.  The tag may also be spelled <emphasis>&lt;CsoundSynthesiser&gt;</emphasis>.
    </para>

    <bridgehead>Options (&lt;CsOptions&gt;)</bridgehead>
    <para>
      Csound <link linkend="CommandFlagsCategory"><citetitle>command line flags</citetitle></link> 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>

    <bridgehead>Orchestra (&lt;CsInstruments&gt;)</bridgehead>
    <para>
      The instrument definitions (orchestra) are put into the Instruments Element. The statements and syntax in this section are identical to the Csound <link linkend="OrchTop"><citetitle>orchestra file</citetitle></link>, 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>

    <bridgehead>Score (&lt;CsScore&gt;)</bridgehead>
    <para>
      Csound score statements are put in the Score Element. The statements and syntax in this section are identical to the Csound <link linkend="ScoreTop"><citetitle>score file</citetitle></link>, 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>
    <para>
      As an alternative Csound score statements can also be generated by an external
      program using the CsScore scheme with an attribute bin. The lines upto the closing
      tag <emphasis>&lt;/CsScore&gt;</emphasis> are copied to a file
      and the external program named is called with that file name and
      the destination score file.  The external program should create a
      standard Csound score.
    </para>

    <bridgehead>Optional Elements</bridgehead>

    <bridgehead>Included Base64 Files (&lt;CsFileB&gt;)</bridgehead>
    <para>
      Base64-encoded files may be included with the tag <emphasis>&lt;CsFileB filename=</emphasis><emphasis>filename</emphasis><emphasis>&gt;</emphasis>, where <emphasis>filename</emphasis> is the name of the file to be included. The Base64-encoded data should be terminated with a <emphasis>&lt;/CsFileB&gt;</emphasis> tag. For encoding files, the csb64enc and  <link linkend="makecsd"><citetitle>makecsd</citetitle></link> utilities (included with Csound 5.00 and newer) can be used. The file will be extracted to the current directory, and deleted at end of performance. If there is an already existing file with the same name, it is not overwritten, but an error will occur instead.
    </para>
    <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. This was added in Csound version 4.07. Note: using this tag is not recommended; use <emphasis>&lt;CsFileB&gt;</emphasis> instead.
    </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. This was added in Csound version 4.07. Note: using this tag is not recommended; use <emphasis>&lt;CsFileB&gt;</emphasis> instead.
    </para>

    <bridgehead>Included Unencoded Files (&lt;CsFile&gt;)</bridgehead>
    <para>
      Unencoded files may be included with the tag
      <emphasis>&lt;CsFile
      filename=</emphasis><emphasis>filename</emphasis><emphasis>&gt;</emphasis>,
      where <emphasis>filename</emphasis> is the name of the file to
      be included. The data should be terminated with a
      <emphasis>&lt;/CsFile&gt;</emphasis> tag alone on a line. The
      file will be extracted to the current directory, and deleted at
      end of performance. If there is an already existing file with
      the same name, it is not overwritten, but an error will occur
      instead.
    </para>

    <bridgehead>Version Blocking (&lt;CsVersion&gt;)</bridgehead>
      <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>

         This was added in Csound version 4.09.
        </para>

    <bridgehead>Licence Information (&lt;CsLicence&gt; or &lt;CsLicense&gt;)</bridgehead>
      <para>
        Licencing details can be included in between the start tag
        <emphasis>&lt;CsLicence&gt;</emphasis> and the end tag
        <emphasis>&lt;/CsLicence&gt;</emphasis>.  There is no format
        for this information, any text is acceptable.  This text will
        be printed by Csound to the console when the CSD is run.
        </para>

        <bridgehead>Licence Information (&lt;CsShortLicence&gt; or &lt;CsShortLicense&gt;)</bridgehead>
        <para>
          From version 6.05 licencing details can be also included in
          between the start tag
          <emphasis>&lt;CsShortLicence&gt;</emphasis> and the end tag
          <emphasis>&lt;/CsShortLicence&gt;</emphasis>.  This offers
          seven well-known licences, coded as as an integer.
        </para>
        <para>
          <simplelist>
            <member>0: "All rights reserved" (default)</member>
            <member>1: "Creative Commons Attribution-NonCommercial-NoDerivatives (CC BY-NC-ND)"</member>
            <member>2: "Creative Commons Attribution-NonCommercial-ShareAlike (CC BY-NC-SA)"</member>
             <member>3: "Creative Commons Attribution-NonCommercial (CC BY-NC)"</member>
             <member>4: "Creative Commons Attribution-NoDerivatives (CC BY-ND)"</member>
             <member>5: "Creative Commons Attribution-ShareAlike (CC BY-SA)"</member>
             <member>6: "Creative Commons Attribution-ShareAlike (CC BY)"</member>
             <member>7: "Licenced under BSD"</member>
             </simplelist>
        </para>

    <bridgehead>Embedded HTML (&lt;html&gt;)</bridgehead>
      <para>
        Any valid HTML code can be embedded in the CSD file. This code should be structured exactly like an ordinary Web page. This code
        can contain any valid HTML, JavaScript, Cascading Style Sheet, WebGL, etc., etc. code.
      </para>
      <para>
        In some Csound front ends and programming environments, including at least CsoundQt or Csound for Android, this page will be parsed, executed,
        and displayed by a Web browser embedded in the environment. JavaScript code in this page will have access to a global <emphasis>csound</emphasis>
        object that implements the following functions, which are a selected subset of the Csound API. The names, data types, and
        uses of these functions are exactly the same as detailed in the Csound API Reference Manual.
        </para>
        <para>
            <programlisting>
[int] getVersion ();
compileOrc (orchestra_text);
[double] evalCode (orchestra_expression);
readScore (score_text);
setControlChannel (channel_name, numeric_value);
[double] getControlChannel (channel_name);
message (message_string);
[int] getSr ();
[int] getKsmps ();
[int] getNchnls ();
// Not a part of the Csound API -- called by the environment to detect whether Csound is running.
[int] isPlaying ();
            </programlisting>
        </para>

        <para>
        The HTML element of the CSD file can be used to create custom user interfaces for the piece, to generate score events and even orchestra code
        using JavaSscript, to store presets for widgets, and for many other purposes. The
        <ulink url="examples/GameOfLife3D.csd"><citetitle>GameOfLife3D.csd</citetitle></ulink> and
        <ulink url="examples/LindenmayerCanvas.csd"><citetitle>LindenmayerCanvas.csd</citetitle></ulink>
        examples demonstrate these uses (tested in CsoundQt; running these examples
        requires additional resources found in the Csound examples directory in GIT).
        </para>

      </section>

      <section id="CommandUnifileExample">
        <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 role="csdtag">&lt;CsoundSynthesizer&gt;</emphasis>;
  <emphasis role="comment">; test.csd - a Csound structured data file</emphasis>

<emphasis role="csdtag">&lt;CsOptions&gt;</emphasis>
  -W -d -o tone.wav
<emphasis role="csdtag">&lt;/CsOptions&gt;</emphasis>

<emphasis role="csdtag">&lt;CsVersion&gt;</emphasis>    <emphasis role="comment">; optional section</emphasis>
  Before 4.10  <emphasis role="comment">; these two statements check for</emphasis>
  After 4.08   <emphasis role="comment">; Csound version 4.09</emphasis>
<emphasis role="csdtag">&lt;/CsVersion&gt;</emphasis>

<emphasis role="csdtag">&lt;CsInstruments&gt;</emphasis>
  <emphasis role="comment">; originally tone.orc</emphasis>
  <emphasis role="ohdr">sr</emphasis> = 44100
  <emphasis role="ohdr">kr</emphasis> = 4410
  <emphasis role="ohdr">ksmps</emphasis> = 10
  <emphasis role="ohdr">nchnls</emphasis> = 1
  <emphasis role="oblock">instr</emphasis>   1
      a1 <emphasis role="opc">oscil</emphasis> p4, p5, 1 <emphasis role="comment">; simple oscillator</emphasis>
         <emphasis role="opc">out</emphasis> a1
  <emphasis role="oblock">endin</emphasis>
<emphasis role="csdtag">&lt;/CsInstruments&gt;</emphasis>

<emphasis role="csdtag">&lt;CsScore&gt;</emphasis>
  <emphasis role="comment">; originally tone.sco</emphasis>
  <emphasis role="stamnt">f</emphasis>1 0 8192 10 1
  <emphasis role="stamnt">i</emphasis>1 0 1 20000 1000 <emphasis role="comment">; play one second of one kHz tone</emphasis>
  <emphasis role="stamnt">e</emphasis>
<emphasis role="csdtag">&lt;/CsScore&gt;</emphasis>

<emphasis role="csdtag">&lt;/CsoundSynthesizer&gt;</emphasis></programlisting>
          </informalexample>
	</para>
    </section>


</section>
<section id="CommandUnifileParFile">
  <title>Command Line Parameter File (.csound6rc)</title>
  <para>
    If the file <emphasis>.csound6rc</emphasis> exists, it will be used to set the command line parameters. These can be overridden. Csound 5.00 and newer versions read this file from the HOME directory first (or the full path file name defined by the CSOUND6RC <link linkend="CommandEnvironment"><citetitle>environment variable</citetitle></link>), and then the current directory. If both exist, options in the .csound6rc in the current directory will have higher precedence. It uses the same form as a <emphasis>.csd</emphasis> file, but no tags are needed. Lines beginning with <emphasis>#</emphasis> or <emphasis>;</emphasis> are treated as comments.
  </para>
  <para>
    A <emphasis>.csound6rc</emphasis> file can contain something like this:
  </para>
  <literallayout>
-+rtaudio=portaudio -odac2 -iadc2 -+rtmidi=winmme -M1 -Q1 -m0
  </literallayout>
  <para>
    In this case, csound will generate real-time output and take realtime input from device 2, using the portaudio driver interface. It will input and output realtime MIDI on interface 1. It will print very few messages (-m0). These options will be used by default when other options are not given inside the &lt;CsOptions&gt; of the .csd file or the command line (See <link linkend="CommandOrder"><citetitle>Order of precendence</citetitle></link>).
  </para>
</section>