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.

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. However, it is a little more complicated to setup than using the commandline mode. The following are instructions on how to enable blue with using the Csound API.

To use the API, you must first have a copy of Csound with the Java interface built, which is contained in a file called csnd.jar. If you used an installer to install Csound like the ones found on Sourceforge, they should have included the csnd.jar file with them. If you build Csound yourself, you will need to build the interface jar, which requires the Java Development Kit (JDK) and SWIG.

The Java API for Csound is split into two parts: the csnd.jar file as well as the lib_jcsound.so native library (this file is csound jcsound.dll on Windows, and lib_jcsound.jnilib on Mac OSX). blue comes with it's own copy of csnd.jar, so to use the API from blue it will need to have access to the native library to work.

The following explains how to setup the API on different platforms.

Windows 

Users using the Windows Installer for Csound should use the doubles version from SourceForge (has -d in the name).  After installing, the installer should setup everything such that blue should work with the API "out of the box".  If for some reason it is unable to do so, or you have compiled Csound yourself and the location of jcsound.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 jcsound.dll.  For example, if the directory where jcsound.dll is located is in c:\myCsound, open up 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_jcsound.so is and modify the blue/etc/blue.conf file.  For example, if the directory where lib_jcsound.so is located is in /usr/lib/jni (the default for Debian/Ubuntu-based systems), open up blue.conf and modify the default so that it contains: 

default_options="--branding blue -J-Xms256m -J-Xmx768m -J-Djava.library.path=/usr/lib/jni"

>> Csound API available: true <<
      

This indicates that the Csound API is available to use as an option. To use the API, you must also enable the Csound API option in Program Options (found from the File Menu). This allows you to selectively turn on and off the API should you want to switch between the API and using the command-line version. (If the API is not available on startup, then the Csound API option in Program Options will be disabled and will not be an option for the user to use.)

If you have configured the CSND_JAR and enabled adding this to the BLUE_LIBS correctly but are getting an error message like this:

_jcsound native code library failed to load.
java.lang.UnsatisfiedLinkError: no _jcsound in java.library.path

This means that you have configured things correctly for Java to find the JAR, but after that, Java can not find the native library which is the actual interface to the Csound API. This native library is called lib_jcsound.so on Linux and OSX and _jcsound.dll on Windows. If you are getting this message, you will need to add the following to the blue starter script for your platform, on the line that calls Java and starts blue:

-Djava.library.path=/path/to/where/_jcsnd.so/is/located

So for example, on Linux you might have the last line look like:

java -Djava.library.path=/home/steven/workspace/csound5 \
     -Xms32m -Xmx256m -DBLUE_HOME="$BLUE_HOME" -cp $BLUE_LIBS blue.Blue "$@"

After enabling the API, you will still need to setup the Csound executable option for Realtime and Disk Render settings in Program Options. However, when using the API, this value gets disregarded, though a value is still required. The typical value to use in this case is "csound". Also to note, by having a valid value here that works without the API, you can switch back and forth between using the API or not without having to reconfigure commandline options.