MAKE CSOUND RUN

Csound and Frontends

The core element of Csound is an audio engine for the Csound language. It has no graphical interface and it is designed to take Csound text files (called ".csd" files) and produce audio, either in realtime, or by writing to a file. It can still be used in this way, but most users nowadays prefer to use Csound via a frontend. A frontend is an application which assists you in writing code and running Csound. Beyond the functions of a simple text editor, a frontend environment will offer colour coded highlighting of language specific keywords and quick access to an integrated help system. A frontend can also expand possibilities by providing tools to build interactive interfaces as well, sometimes, as advanced compositional tools.

In 2009 the Csound developers decided to include CsoundQt as the standard frontend to be included with the Csound distribution, so you will already have this frontend if you have installed any of the recent pre-built versions of Csound. Conversely if you install a frontend you will require a separate installation of Csound in order for it to function. If you experience any problems with CsoundQt, or simply prefer another frontend design, try WinXound, Cabbage or Blue as alternative. 

Which version of Csound should I choose?

Spring 2013 has been an exciting time for Csound users with the release of Csound6. Csound6 has a lot of new features like on-the-fly recompilation of Csound code (enabling forms of live-coding), arrays, new syntax for using opcodes, a redesigned C/C++ API, better threading for usage with multi-core processors, better real-time performance, etc... but one must bear in mind that Csound6 is still a work-in-progress and may have stability issues.

If you are proficient with compiling software for your computer, know how to use git, are already a programmer wanting to learn an audio-specific language, then Csound6 might be for you as it offers a few features that resemble general purpose languages like functional-style syntax, increment/decrement operators, better means of data abstraction (arrays), etc...

On the other hand, if you are new to Csound or to programming in general, your best bet would be to install Csound5, as most documentation still refers to that version. Everything you will learn about Csound5 will work in Csound6, but you will benefit from the added stability and better documentation (including this manual) that Csound5 still provides over Csound6.

Of course, it is possible to have Csound5 installed as the main package and still install a local copy of Csound6 for testing purposes, but then again, certain skills are required pertaining to compiling software from source code¹ so beginners should really consider learning Csound5 and then move to Csound6 once it has become the official version.

How to Download and Install Csound

To get Csound you first need to download the package for your system from the SourceForge page: http://sourceforge.net/projects/csound/files/csound5 (or http://sourceforge.net/projects/csound/files/csound6 if you have decided to use Csound6).

There are many files here, so here are some guidelines to help you choose the appropriate version.

Windows

Windows installers are the ones ending in .exe. Look for the latest version of Csound, and find a file which should be called something like: Csound5.17-gnu-win32-d.exe. The important thing to note is the final letter of the installer name, which can be "d" or "f". This specifies the computation precision of the Csound engine. Float precision (32-bit float) is marked with "f" and double precision (64-bit float) is marked "d". This is important to bear in mind, as a frontend which works with the "floats" version will not run if you have the "doubles" version installed. More recent versions of the pre-built Windows installer have only been released in the "doubles" version.

After you have downloaded the installer, you might find it easiest just to launch the executable installer and follow the instructions accepting the defaults. You can, however, modify the components that will be installed during the installation process (utilities, front-ends, documentation etc.) creating either a fully-featured installation or a super-light installation with just the bare bones.

You may also find it useful to install the Python opcodes at the this stage - selected under "Csound interfaces". If you choose to do this however you will have to separately install Python itself. You will need to install Python in any case if you plan to use the CsoundQt front end, as the current version of CsoundQt requires Python. (As of March 2013, Version 2.7 of Python is the correct choice.)

Csound will, by default, install into your Program Files folder, but you may prefer to install directly into a folder in the root directory of your C: drive.

Once installation has completed, you can find a Csound folder in your Start Menu containing short-cuts to various items of documentation and Csound front-ends.

The Windows installer will not create any desktop shortcuts but you can easily do this yourself  by right-clicking the CsoundQt executable (for example) and selecting "create shortcut". Drag the newly created shortcut onto your desktop.

Mac OS X

The Mac OS X installers are the files ending in .dmg. Look for the latest version of Csound for your particular system, for example a Universal binary for 10.8 will be called something like: csound5.19.02-OSX10.8-universal.dmg. When you double click the downloaded file, you will have a disk image on your desktop, with the Csound installer, CsoundQt and a readme file. Double-click the installer and follow the instructions. Csound and the basic Csound utilities will be installed. To install the CsoundQt frontend, you only need to move it to your Applications folder.

Linux and others

Csound is available from the official package repositories for many distributions like OpenSuse, Debian, Ubuntu, Fedora, Archlinux and Gentoo. If there are no binary packages for your platform, or you need a more recent version, you can get the source package from the SourceForge page and build from source. You will find the most recent build instructions in the Csound MediaWiki on Sourceforge (Csound5) and in the new Sourceforge Wiki (Csound6). Detailed (but perhaps outdated) information can also be found in the Building Csound Manual Page.

Note that the Csound repository has moved from cvs to git. After installing git, you can use this command to clone the Csound6 repository, if you like to have access to the latest (perhaps unstable) sources:

git clone git://git.code.sf.net/p/csound/csound6-git

You will find the last release on the master branch, and the latest sources on the develop branch.

iOS

Thanks to Steven Yi and Victor Lazzarini, Csound has been ported to Android and iOS.²  

The iOS files for Csound are found in a subfolder of the Csound files on SourceForge. The location is http://sourceforge.net/projects/csound/files/csound5/iOS/ for Csound5. For Csound6, you will find the iOS files in the version folder in http://sourceforge.net/projects/csound/files/csound6/.

The file of interest (in the Csound5 folder) is csound-iOS-X.XX.XX.X.zip where (X.XX.XX.X is the version number). The archive file contains the CSound programming library, sample code, and a PDF introduction to programming CSound for iOS devices, written by Victor Lazzarini and Steven Yi.

This distribution is aimed at iOS programmers, there are no apps that can be installed directly: this is due to the fact that iOS apps cannot be installed directly. iOS apps have to be downloaded and installed from Apple's app store.

On Apple's app store, there are some examples of apps that use Csound. Below, is a a small sample of apps that make use of Csound:

• csGrain, developed by the Boulanger Labs (http://www.boulangerlabs.com), is a complex audio effects app that works with audio files or live audio input.
• Portable Dandy, an innovative sampler synthesiser for iOS (see http://www.barefoot-coders.com).
• iPulsaret, an impressive synthesizer app (see http://www.densitytigs.com). 

This is an on-going situation, and we can expect to see more apps made available as time goes by. 

Android

The Android files for Csound are found in a subfolder of the Csound files on SourceForge. At the time of writing the location is http://sourceforge.net/projects/csound/files/csound5/Android/  for Csound5. For Csound6, you will find the Android files in the version folder in http://sourceforge.net/projects/csound/files/csound6/.

Two files are of interest here (in the Csound5 folder). One is a CSD player which executes Csound files on an Android device (the CSD player app is called CsoundApp-XXX.apk where XXX is the version number of the app).

The other file of possible interest to is csound-android-X.XX.XX.zip (where X.XX.XX is the version number), this file contains an Android port of the Csound programming library and sample Android projects. The source code for the CSD player mentioned above, is one of the sample projects. This file should not be installed on an Android device.

To install the CsoundApp-XXX.apk on an Android device the following steps are taken:

1. The CsoundApp-XXX.apk file is copied onto the Android device, for example /mnt/sdcard/download or something similar.
2. One or more CSD files (not included in the distribution) should be copied to the device's shared storage location: this is usually anywhere in or below /mnt/sdcard
3. Launch a file explorer app on the device and navigate to the folder containing the file CsoundApp-XXX.apk (copied in step 1). Select the apk file and when prompted, select to install it. The app is installed as "CSD Player".
4. In the device's app browser (the screen which is used to launch all the apps on the device) run the "CSD Player" app.
5. CSD Player displays its initial screen. Tap the "Browse" button to find a CSD file to play on your device: CSD Player displays a file browser starting at the device's shared storage location (usually /mnt/sdcard). Select a csd file that you have copied to the device (step 2).
6. Tap the play toggle to play the selected CSD.
   

Install Problems?

If, for any reason, you can't find the CsoundQt (formerly QuteCsound) frontend on your system after install, or if you want to install the most recent version of CsoundQt, or if you prefer another frontend altogether: see the CSOUND FRONTENDS section of this manual for further information. If you have any install problems, consider joining the Csound Mailing List to report your issues, or write a mail to one of the maintainers (see ON THIS RELEASE).

The Csound Reference Manual

The Csound Reference Manual is an indispensable companion to Csound. It is available in various formats from the same place as the Csound installers, and it is installed with the packages for OS X and Windows. It can also be browsed online at The Csound Manual Section at Csounds.com. Many frontends will provide you with direct and easy access to it.

How to Execute a Simple Example

Using CsoundQt

Run CsoundQt. Go into the CsoundQt menubar and choose: Examples->Getting started...-> Basics-> HelloWorld

You will see a very basic Csound file (.csd) with a lot of comments in green.

Click on the "RUN" icon in the CsoundQt control bar to start the realtime Csound engine. You should hear a 440 Hz sine wave.

You can also run the Csound engine in the terminal from within QuteCsound. Just click on "Run in Term". A console will pop up and Csound will be executed as an independent process. The result should be the same - the 440 Hz "beep".

Using the Terminal / Console

1. Save the following code in any plain text editor as HelloWorld.csd.

   EXAMPLE 02A01_HelloWorld.csd 

<CsoundSynthesizer>
<CsOptions>
-odac
</CsOptions>
<CsInstruments>
;Example by Alex Hofmann
instr 1
aSin      oscils    0dbfs/4, 440, 0
          out       aSin
endin
</CsInstruments>
<CsScore>
i 1 0 1
</CsScore>
</CsoundSynthesizer>

2. Open the Terminal / Prompt / Console

3. Type: csound /full/path/HelloWorld.csd

where /full/path/HelloWorld.csd is the complete path to your file. You also execute this file by just typing csound then dragging the file into the terminal window and then hitting return.

You should hear a 440 Hz tone.

1. for Windows users in particular, compiling Csound can be tedious. On linux systems it may be easier to do, but one would still need to learn how to use cmake to configure Csound6.^{^}
2. Steven Yi and Victor Lazzarini: Csound on Android (Paper at the Linux Audio Conference 2012); Brian Redfern: Introducing the Android CSD Player (Csound Journal Issue 17 - Fall 2012) ^{^}