The Unified File Format, 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 .csd. This format was originally introduced by Michael Gogins in AXCsound.

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

Structured Data File Format

Mandatory Elements

The first tag in the file must be the start tag <CsoundSynthesizer>. The last tag in the file must be the end tag </CsoundSynthesizer>. This element is used to alert the csound compiler to the .csd format. All text before the start tag and after the end tag is ignored by Csound. The tag may also be spelled <CsoundSynthesiser>.

Options (<CsOptions>)

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

Orchestra (<CsInstruments>)

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 (sr, kr, etc.) This Instruments Element is delimited with the start tag <CsInstruments> and the end tag </CsInstruments>.

Score (<CsScore>)

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 <CsScore> and the end tag </CsScore>.

Optional Elements

Included Base64 Files (<CsFileB>)

Base64 encoded files may be included with the tag <CsFileB filename=filename>, where filename is the name of the file to be included. The Base64 encoded data should be terminated with a </CsFileB> tag. For encoding files, the csb64enc and makecsd 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.

Base64 encoded MIDI files may be included with the tag <CsMidifileB filename=filename>, where filename is the name of the file containing the MIDI information. There is no matching end tag. New in Csound version 4.07. Using this tag is not recommended; use <CsFileB> instead.

Base64 encoded sample files may be included with the tag <CsSampleB filename=filename>, where filename is the name of the file containing the sample. There is no matching end tag. New in Csound version 4.07. Using this tag is not recommended; use <CsFileB> instead.

Version Blocking (<CsVersion>)

Versions of Csound may blocked by placing one of the following statements between the start tag <CsVersion> and the end tag </CsVersion>:

Before #.#

or

After #.#

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

#.#

New in Csound version 4.09.

Licence Information (<CsLicence> or <CsLicense>)

Licencing details can be included in between the start tag <CsLicence> and the end tag </CsLicence>. 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.