Installing Csound

Using Blue with command-line Csound
Using Blue with the Csound API

Blue is able to interact with Csound either by calling Csound like a command-line program (classic Blue), or by directly interacting with Csound via the Csound API. Instructions on setting up Blue for each method is described below as well as discussion on benefits and limitations.

Using Blue with command-line Csound

This may be considered "classical" Blue usage and interaction with Csound as this was the method by which Blue ran with Csound for the first eight years in existance. The way Blue operates in this mode is by rendering the .Blue project into a temporary CSD file on disk, then calling Csound with that temporary CSD file in the same way as if you were on a command-line shell and executing Csound yourself with that file.

The benefit to this mode of Csound usage is that it is easier to switch out your version of Csound or use multiple versions of Csound on the same computer. It is also a little more stable than using the API in that if Csound crashes for some reason, it won't take down Blue with it. Also, it may be more performant to use the command-line mode. These benefits however need to be weighed against the benefits of using the API, which is described below.

To use the command-line version, one needs to set up the Csound executable option for Realtime and Disk Render settings in Program Options.

Using Blue with the Csound API

Enabling Blue to use the Csound API when rendering with Csound opens up the ability to manipulate and edit widget values and automations in realtime during a render, as well as the ability to use BlueLive on Windows. Because of its enhancement to the user-experience while rendering and composing, it is now the preferred method of using Blue with Csound. Blue should work out-of-the-box with the API if Csound is installed using the installers provided on Github, or installed via a package manager if on Linux.

Note

Blue currently only works with the API if the version of Csound used is compiled using 64-bit doubles. (The float version is not currently supported when using the API.) There are technical difficulties in supporting two different versions of Csound API in the same build and it is not known if or when the float build will be supported. For users interested in using the float build of Csound with Blue, you will need to run Blue using the command-line Csound mode.

Additionally, the architecture that Csound is compiled for must match the architecture of the Java runtime you are using. For example, on Windows, Csound is currently only built for x86_64/amd64 CPU (i.e. 64-bit Windows) and not x86 (i.e. 32-bit Windows). In this case, you will need to run Blue using a 64-bit Java Runtime. For OSX, this is not an issue as Csound is compiled as a universal binary for both i386 and x86_64. On Linux, it is likely that the version of Csound you install/compile and the Java Runtime that you install will likely be the same, but if the API does not show as available it may be something to check.

The Java API for Csound is split into two parts: the csnd6.jar file as well as the lib_jcsound6.so native library (this file is called _jcsound6.dll on Windows, and lib_jcsound6.jnilib on Mac OSX). Blue comes with its own copy of csnd6.jar; to use the API from Blue it will need to have access to the native library to work. If the API is not enabled for use out-of-the-box, the following explains how to setup the API on different platforms.

Windows

Users using the Windows Installer for Csound should use the double precision version from Github. (This is the default.) After installing, the installer should setup everything such that Blue should work with the API. If for some reason it is unable to do so, or you have compiled Csound yourself and the location of jcsound6.dll is different from where it is installed with the installer, you can modify the Blue/etc/Blue.conf file to tell Blue where to find the _jcsound6.dll. For example, if the directory where jcsound6.dll is located is in c:\myCsound, open up Blue/etc/Blue.conf and modify the default so that it contains:

default_options="--branding Blue -J-Xms256m -J-Xmx768m -J-Djava.library.path=c:/myCsound"
        
Linux

Linux users should install a doubles version of Csound. The version of Csound found in package repositories should be one compiled for doubles. After installing Csound and the Java interface for Csound, locate where lib_jcsound6.so is and modify the Blue/bin/Blue file. Search for the lines that contain "-J-Djava.library.path=/usr/lib/jni" and modify /usr/lib/jni (the default for Debian/Ubuntu-based systems) to the directory where lib_jcsound.so is located.

Mac OSX

Mac OSX users should use the installer for Csound from Github. The installer should install both the float and doubles version of Csound. The lib_jcsound.jnilib will be installed into /Library/Java/Extensions. If you are compiling your own version of Csound, you can remove the symlink in /Library/Java/Extensions and either symlink your your version there or copy it into that folder.

Checking the API is Enabled

To check if the API is enabled, open Blue and open up the Program Options. This is available from the Blue->Preferences menu option on OSX, and from the Tools->Options menu option Windows and Linux. In the Blue tab, under both Disk and Realtime Render settings, there is an option called "Render Method". If Csound 6 is availble on your system and Blue was able to find it, it will show a "Csound 6 API" option. If the Csound 6 Java API could be loaded, you will only have the "Commandline Runner" option which is always available.