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.

After locating the csnd.jar, take note of the location of the file. You will next have to edit the starter script for your platform (blue.bat, blue.sh, or blue.command). These scripts all contain a line that says "CSND_JAR=xxx" where the xxx is a path. You will need to replace that xxx with the location of the csnd.jar. It is suggested that one makes a copy of the starter script and gives it new name, such as "myblue.bat" or "myblue.sh", before editing. This is because if you upgrade blue by running the installer with a newer version, you copy of the starter script will not be overwritten.

Also, you will need to remove the commenting from the lines that contains "CSND_JAR". On Windows, you will need to remove the "@rem" at the beginning of the lines so you should have lines like:

set CSND_JAR=c:\work\workspace\csound5\csnd.jar
set BLUE_LIBS=%BLUE_LIBS%;%CSND_JAR%
        

On Linux and OSX, you will need to remove the "#" at the beginning of the lines and so you should have lines like:

CSND_JAR=/home/steven/workspace/csound5/csnd.jar
BLUE_LIBS=$BLUE_LIBS:$CSND_JAR
        

If everything is setup correctly, next time you start blue, in the console window that appears before the main blue interface shows up, you should see the following line printed:

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