JCollider -- version 0.36 (built 11-oct-09) --

statement

JCollider is a java library to build clients for the SuperCollider server architecture. While staying rather compact, it provides a lot of the functionality found in the SuperCollider Language (sclang) application. JCollider uses the same concept of mirroring the server (scsynth) objects on the client side as sclang, and its API is fairly similar to classes found in sclang. Some additional GUI helper classes are provided. JCollider is (C)opyright 2005-2009 by Hanns Holger Rutz. All rights reserved. JCollider is released under the GNU General Public License which protects your freedom and ensures that products built using this library are also free software. The software comes with absolutely no warranties.

To contact the author, send an email to contact at sciss.de. For project status, API and current version, visit www.sciss.de/jcollider.

requirements / installation

JCollider is platform independant, but requires a Java™ 1.4 SE runtime environment (JRE) or development kit (JDK). since it is designed to control a supercollider server, you will have to install one, if you haven't yet done so. the main supercollider portal is supercollider.sf.net. JCollider uses the NetUtil OSC library which is licensed under the GNU Lesser General Public License and which is included in this release. To access the source code of NetUtil, please download the full package from www.sciss.de/netutil.

download

The current version can be downloaded here:

• sourceforge.net/projects/jcollider

documentation

Documentation comes in the form of JavaDoc. The generate the docs, open a terminal, cd into the JCollider folder and run:

$ ant doc

there is no real tutorial or manual at the moment, however if you are familiar with sclang, it is straight forward to get started. the API documentation (see below) is not yet complete but already quite robust.

• API index (local copy)
• API index (online)

compilation / usage

Please read the DevelopersNeeded note.

The downloaded archive comes already with a built version of JCollider, that is build/JCollider.jar to you may not need to compile it yourself.

The source code can be compiled using Eclipse SDK 3.2+ (www.eclipse.org) and Apache Ant 1.6.5+ (ant.apache.org). You need to install Ant-Contrib as well (first install Ant if you do not have it, then download Ant-Contrib and copy ant-contrib.jar into Ant's lib folder). The Eclipse project file is configured to run the regular Ant build file. You can make a clean build just with Ant from the terminal:

$ ant clean jar
$ ant test

The "test" will just launch the JCollider demo so you can see if the build works; you can leave away that task. By default, NetUtil is included in the resulting file build/JCollider.jar. If wish to link externally to it, you can build like this:

$ ant -Dplain=true clean jar

the original demo project is included in this build and can be executed as follows:

$ java -jar build/JCollider.jar --test1

the demo opens two frames, one containing a list of synth defs, the other one being a small server window just like you know from sclang. first check, that the path name to the application is correct, alternatively start the server manually before launching the demo. now select a synth definition from the tables and press the play button. to stop all synths, press the stop button. to view the synth def, press one of the next two buttons. to see a tree of all known nodes, press the right most button.

note that some synth defs will only run on mac os because they use mac-only ugens (e.g. MouseX). also note that CombDist and RingMod are insert effects which have to be started before starting an oscillator synth def.

Alternatively, --test2 runs a demo for generating a SynthDef with controls which can be operated from a GUI.

projects using jcollider

• Eisenkraut – a cross-platform audio file editor.
• Superj – an Open Sound Control (OSC) enabled audio scripting server.
• SwingOSC – an OpenSoundControl (OSC) server intended for scripting Java(tm), such as to create graphical user interfaces with AWT or Swing classes.
• Tacchi – combines the multi-touch/fiducial recognition functionality of the opensource reacTIVision, and Community Core Vision projects with the strength of Supercollider in the form of JCollider and the strength of the Java 2D libraries to allow for an opensource alternative to the Reactable.

Please let me know when you want to have your projects added here.

to-do / known issues

• proper documentation of Synth, Group, Bus
• add missing methods from sclang counterparts
• add GUI panel for server options

change history

v0.36 (sep 2009 - SVN rev. 25)

• Bus: adding set(n)(Msg), get(n)(Msg), fill(Msg)

v0.35 (sep 2009 - SVN rev. 19)

• Updated ugen infos: DiskOut number of outputs

v0.34 (jul 2009 - SVN rev. 16)

• Updated ugen infos from latest SuperCollider
• Control: possible to create multiinput control with just one name
• Server: default bufsize 64k, better boot thread quitting
• Synth: get(n)(Msg) added, grain added
• Fixed some threading issues
• Uses ScissLib now
• Uses ant doc target

v0.32 (feb 2008 - SVN rev. 3)

• ServerOptions: added verbosity and rendezvous
• Node: added register, unregister
• UGenInfo: added binary file format (much faster)

v0.31 (nov 2007)

• switched over to Eclipse IDE and Ant build tool
• Buffer: added getDuration, allocConsecutive, allocReadChannel, readChannel methods

v0.30 (jul 2007)

• updated for new NetUtil version

v0.29 (oct 2006)

• updated for new NetUtil version; allows to talk to server using TCP
• bug fixes and improvements in NodeWatcher
• slight modfications of OSCMultiResponder and OSCResponderNode, see readme_api_changes.txt for details
• v0.291 fixes missing server.start() calls in demos and boot thread, includes TCP fixes from NetUtil 0.31
• v0.292 fixes a bug in NodeWatcher.dispose()

v0.28 (jul 2006)

• incorporates some sclang updates, mainly variable bus allocator classes in ServerOptions and Server.
• Server's alive thread more robust against occasional server irresponsiveness
• extended method documentation
• added a couple of missing methods
• added ControlSpec, Warp, EZSlider
• bugfixes (OSCMultiResponder et al.)

v0.27 (feb 2006)

• bugfix in SynthDef: recognizes unnamed controls generated from arrays

v0.26 (nov 2005)

• bugfix in SynthDef: recognizes LagControl, TrigControl

v0.24 (oct 2005)

• adds write() methods to Buffer
• added /fail support for Server.sendMsgSync() ; added Server.sendBundleSync()

v0.23 (oct 2005)

• new NodeWatcher class, new GUI classes NodeTreeManager and NodeTreePanel
• Node is abstract now, and implements the TreeNode interface which nicely interacts with the new GUI classes ; Nodes can be named for human readability
• removed setGroup, setRunning and setPlaying statements from the Node classes; this job must be explictely done now by a NodeWatcher or the like, which is a much cleaner solution
• after booting, server will call initTree before dispatching the server event

v0.21 (sep 2005)

• fixed bug in Server.boot() (didn't reset the booting status when boot failed)

v0.2 (sep 2005)

• first version separately released. alpha stadium, probably totally buggy