blue requires a Java 1.6 (also known as 6.0) or greater JVM (Java Virtual Machine). To test to see if you have a JVM installed and what version, at a command prompt type "java -version". If you see something along the lines of "command not found" then you need to install a Java Virtual Machine.
A Java JVM for Linux, Windows, and Solaris can be found at:
From here, select the version of Java you want to use (must be 1.6/6.0 or higher for blue), and then choose the download for your platform. There will be an option to download either the "JRE" or the "SDK". The JRE is just what is required to run java programs and is all that is required to run blue. If you're planning to do Java development, then download the SDK as it includes the JRE as well as all of the Java development tools.
To install blue, you should download the latest ZIP file from the blue Sourceforge page here. For OSX, download the zip that has "OSX" in the name. For other platforms, download the version that does not have "OSX" in the name.
Unzip the file to a location of your choice. After unzipping, locate the bin folder and use either the "blue" script or "blue.exe", depending if your are on Linux/OSX or Windows. For OSX users, unzipping the zipp should produce a blue.app directory that will appear as a clickable application. Simply double-clicking this should start blue.
Note: After starting blue, you may want to explore the example projects and pieces found in the blue\example folder (or right-click and explore contents of blue.app/example if on OSX).
The section below has notes for individual platforms.
Unless you are using a mouse that emulates a second mouse button, you will have to use a combination of the "open apple" key plus a mouse click for all "rt-clicks" that are mentioned in this documentation.
To make use of the function key shortcuts (F1-F12), you will also need to tick System Preferences, Keyboard and Mouse, "F1-F12 to control software features". (This affects recent versions of OSX.)
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.
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.
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.
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 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"
Mac OSX users should install a doubles version of Csound. The version of Csound should be one compiled for doubles. As of the time of this writing, the Mac Csound installer does not include a doubles version of the Java API. The following are instructions on how to setup OSX 10.6 for API usage with blue.
If everything is setup correctly, after starting blue... [INFORMATION NOT YET COMPLETE, the following is out of date and needs to be updated!]
>> 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:
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.