Skip to content
Csound Reference Manual (English)
Python Makefile CSS
Find file
Failed to load latest commit information.
STKopcodes removed text about SCons and updated text to Csound6
command Typos
csbeats initial
cscore Missing files
csound5 Starting to change build instructions from scons to cmake
deprecated work on loscilx page, and minir on sndloop
examples-xml compress2 and simpler examples
examples compress2 and simpler examples
experimental Added Note Releases and changed version number to 6.03
imageopcodes initial
images initial
math Changed version number to 6.00.1, added release notes and activated F…
midi i before e EXCEPT after c --- so receive
misc small update
miscopcodes initial tidying
opcodes Typos
orch Changed version number to 6.00.1, added release notes and activated F…
oscnetwork initial
overview change info on mailing lists
plugin initial
preface Release notes updated
score time correction
scoregens Updated from source code.
siggen Added linto and tlineto to envelope.xml
sigio Websocket manual entry
sigmod Minor fix
spectral minor correction (link)
strings initial
table initial
utility adjust interp for third optional arg
vectorial transformed emphasis tag to link
xsl Minor fix
zak initial
.gitignore added .gitignore to ignore html directory, which only contains genera…
Makefile Added release notes for version 6.06 and changed version number in ma… Better looking readme edits to the manual and categories
copying.txt Missing files Updates for Csound 6 manual build. initial tidying
csound.css initial tidying Quick and dirty fix for frames manual
manual.xml compress2 and simpler examples
opcode_list.txt added current opcode_list.txt for use in initial tidying
opcodes.xml fixing stupid mistake initial tidying

About the Manual

The Csound Reference Manual is written in Docbook-XML. More information about Docbook-XML can be found at the following links:

If you find problems or have suggestions, please report them on the csound developer mailing list.

Building the Manual

To build the manual, a number of different tools are required, depending on what target output is desired. All targets require xsltproc and the Docbook XML DTDs to be installed and findable by xsltproc. The Docbook XSL stylesheets have to be installed too. The location of the stylesheets can be noted via the XSL_BASE_PATH variable:

$ make XSL_BASE_PATH=path/to/xsl/installation <target>

The default is /usr/share/xml/docbook/stylesheet/nwalsh/

On Linux, most distributions include these programs, or are available on packaging repositories for the respective distribution.

For Windows, xsltproc can be found as part of the Cygwin environment ( A natively compiled version for windows can be found at:

Mac OS 10.5 (leopard) includes xsltproc.

(NOTE: If someone works on OSX or OS9 and finds xsltproc for these platforms or another suitable XSLT processor, please update this documentation.)

The manual is made using make with the included Makefile. For example to make the html (canonical) version:

$ make html

is all that is needed.

To begin a new build, use

$ make clean

Other targets include pdf, pdfA4 and htmlXO. See the makefile for distribution and other targets.



$ make html

Requires: Python (to generate the frames version, and to update the Quick Reference)



$ make pdf


$ make pdfA4


FOP can require a lot of memory, so it is recommended to edit the file and add "-Xmx384m" to the last line, so it reads as such:

$ JAVACMD -Xmx384m -classpath "$LOCALCLASSPATH" $FOP_OPTS org.apache.fop.apps.Fop "$@"

This increases the max ram the VM can use to 384megs, which you'll need for FOP to run as the manual is fairly large.



$ make htmlhelp

Requires: Microsoft HTML Help Workshop (

This target compiles a Windows .chm file, a format that replaced WinHelp.

Editing the Manual

Modifying an Entry

In general, be careful to be mindful that these files are XML and must be valid. All tags that are openned must be closed, i.e. My Information.

Also, Docbook-XML has a DTD that describes what is well-formed for the document, meaning that certain tags only allow other tags within it. For more information on valid Docbook tags, see "Docbook: The Definitive Guide" by Norm Walsh, available at

Adding an Opcode Entry

First, the best place to start is to take an existing entry and use that as a template. All opcode entries are organized in the opcodes folder. You can base your entry on an existing entry, or use Opcodes/templates.xml.

To incorporate a new entry into the manual, a few things are required.

  1. Add the entry as an entity in manual.xml. For example, if you put the myOpcodeEntry.xml in the opcodes directory, then this entry should be the one to add in manual.xml:

    <!ENTITY opcodesmyopcodeentry SYSTEM "opcodes/myOpcodeEntry.xml">

  2. Add the entry to opcodes/top.xml by using the entity. This will actually add the entry to the reference manual. The entries are alphabetically ordered, so just find where your opcode should be in the list and add:


The above uses the entity that was defined in the manual.xml file (think of it like an #include).

  1. After that, you'll probably want to find the section headers where the opcode should be cross-referenced from. For example, if myOpcodeEntry should be categorized with other pvs opcodes in spectral/realtime.xml, it would be added in that file as:

    My Opcode Entry

The linkend attribute above points to a docbook ID. The "myOpcodeEntry" ID should be defined in the myOpcodeEntry.xml, probably to be done at the top level like this:

<refentry id="myOpcodeEntry">

Repeat step 3 for any sections you think this opcode should be categorized in.

  1. Add the appropriate info tag so the opcode will be properly categorized in the Quick Reference. If no info tag is provided the opcode will appear in 'Miscellaneous'. Consult available categories in

  2. If possible reference the opcode in the appropriate section in Section II of the manual, and add the necessary cross references.

  3. For transforming the myOpcodeEntry.csd example file to myOpcodeEntry.csd.xml (in examples-xml), use the or script. The former uses the Csound API for an opcode list, while the latter uses a file opcode_list.txt (which is similar to the result of the command 'csound -z'). For instance: $ python -f genarray_i.csd will create the file genarray_i.csd.xml from genarray_i.csd for use in the genarray_i opcode entry.

For Maintainers

There are several targets that prepare files for release. It is important to remember to change the version number so that files and content are generated with that number. It must be changed both in manual.xml and the Makefile. It is also a good idea to update the What's new section for each release.

General XML Editing Tips

  • The "<" and ">" symbol, when used as text within XML tags, need to be escaped. The corresponding entities to use are "<" and ">".
  • The refsect1 tag ends with the number 1, not the letter l.
  • You can test your XML file by opening it in a web browser (i.e. Firefox, Mozilla, Internet Explorer, etc.). Most browsers will display the XML file if it is correct or will give you an error message if it the XML file is not valid, as well as give you information on where it is in error.

Using a dedicated XML editor takes some of the pain out of editing the manual. Something like emacs in sgml mode or Kate in XML mode are very helpful.

Something went wrong with that request. Please try again.