Skip to content

The .csdfile format

The Unified File Format enables the orchestra and score files, as well as command line flags, to be combined in one file. The file has the extension .csd.

The file is a structured data file which uses markup language, similar to any SGML (Standard Generalized Markup Language) 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.

Main Elements

Enclosing tag <CsoundSynthesizer>

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 // or # are treated as comments.

If the Options element is missing, the default options will be used:

-s -otest -b1024 -B1024 -m7 -P128

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. This Instruments Element is delimited with the start tag <CsInstruments> and the end tag </CsInstruments>.

Usually the CsInstruments tag starts with a declaration of the fundamental constants sr (sample rate, default 44100), ksmps (number of samples per control cycle, default 10, recommended 32 or 64), nchnls (number of channels, default 10) and 0dbfs (amplitude value equal to zero dB full scale, default 32767, recommended 1).

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>.

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 </CsScore> 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.

If the Score Element is missing, the score will be considered as being empty, thus causing Csound to run without a distinct termination.

Optional Elements

Included Base64 Files <CsFileB>

Base64-encoded files may be included with the tag <CsFileB filename=myfile>, where myfile 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 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=myfile>, where myfile is the name of the file containing the MIDI information. There is no matching end tag. Note: using this tag is not recommended; use <CsFileB> instead.

Base64-encoded sample files may be included with the tag <CsSampleB filename=myfile>, where myfile is the name of the file containing the sample. There is no matching end tag. Note: using this tag is not recommended; use <CsFileB> instead.

Included Unencoded Files <CsFile>

Unencoded files may be included with the tag <CsFile filename=myfile>, where myfile is the name of the file to be included. The data should be terminated with a </CsFile> 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.

Version Blocking <CsVersion>

Versions of Csound are 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:

#.#

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.

Short Licence Information <CsShortLicence> or <CsShortLicense>

From version 6.05 licencing details can be also included in between the start tag <CsShortLicence> and the end tag </CsShortLicence>. This offers seven well-known licences, coded as as an integer.

0: "All rights reserved" (default)
1: "Creative Commons Attribution-NonCommercial-NoDerivatives (CC BY-NC-ND)"
2: "Creative Commons Attribution-NonCommercial-ShareAlike (CC BY-NC-SA)"
3: "Creative Commons Attribution-NonCommercial (CC BY-NC)"
4: "Creative Commons Attribution-NoDerivatives (CC BY-ND)"
5: "Creative Commons Attribution-ShareAlike (CC BY-SA)"
6: "Creative Commons Attribution-ShareAlike (CC BY)"
7: "Licenced under BSD"

Embedded HTML <html>

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.

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 csound 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.

[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 ();

Cabbage <Cabbage>

This is a tag which is used by the Cabbage frontend for its Graphical User Interface.