OSC protocol library written in Java
Java Other

README.markdown

Overview

Open Sound Control (OSC) is a content format, though it is often though of as a protocol for the transmission of data over a network. Its main use and origin is that of a replacement for MIDI as a network-protocol for the exchange of musical control data between soft- and hardware over a UDP-IP network. Applications like SuperCollider, Max/MSP, and Reaktor (among others) use OSC for network communication. Nowadays it is also used in other fields, for example in robotics.

JavaOSC is a library that gives Java programs the capability of sending and receiving OSC. It is not, in itself, a usable program.

The latest release version of the library is available on Maven central or the project homepage.

Latest development sources can be found on github.

Folder structure

  • modules/core/src/main/java/ JavaOSC core sources
  • modules/ui/src/main/java/ JavaOSC UI sources
  • modules/core/src/main/resources/puredata/ PureData file for the PD example
  • modules/core/src/main/resources/supercollider/ SuperCollider files for the examples
  • modules/*/target/ where build files end up

How to

Run the Demo UI

... with SuperCollider

JavaOSC is not a standalone application, but designed to be used in other applications. Though, there is a very basic application, created by John Thompson, for demonstration purposes.

To run the demo app, make sure you have all parts packaged and installed:

mvn install

Then start the UI:

cd modules/ui
mvn exec:java

Next, launch SuperCollider, open the file located in the modules/core/src/main/resources/supercollider/ directory, and load the synthdef into SuperCollider. Start the SC local server. In the JavaOSC Demo UI, click the "All On" button and start moving the sliders. You should hear the sounds change. To see what messages the UI is sending, run either the CNMAT dumpOSC, or turn on dumpOSC in SuperCollider.

... with PD

There is also a PureData patch created by Alexandre Quessy, available here.

To try the demo UI with PureData, launch (this is important!) pd-extended and open the file modules/core/src/main/resources/puredata/javaosc.pd. Turn down the volume a bit at first, as it might be very loud. Click the "All On" button, and start moving the sliders. You should hear the sounds change. To see what messages the UI is sending, just look in the PD window or in the terminal.

Use the library

The classes that deal with sending OSC data are located in the com.illposed.osc package. The core classes are com.illposed.osc.OSCPort{In, Out}, com.illposed.osc.OSCMessage and com.illposed.osc.OSCBundle.

The common way to use the library is to instantiate an OSCPort connected to the receiving machine and then call the send() method on the port with the packet to send as the argument.

There are some associated JUnit tests, which also contain code that may illustrate how to use the library. They can be run with mvn test.

Release a SNAPSHOT (devs only)

mvn clean deploy

To release a development version to the Sonatype snapshot repository only.

Release (devs only)

Prepare "target/" for the release process

mvn release:clean

Setup for signing the release

To be able to sign the release artifacts, make sure you have a section in your ~/.m2/settings.xml that looks like this:

<profiles>
	<profile>
		<id>ossrh</id>
		<activation>
			<activeByDefault>true</activeByDefault>
		</activation>
		<properties>
			<gpg.executable>gpg2</gpg.executable>
			<!--
				This needs to match the `uid` as displayed by `gpg2 --list-keys`,
				and needs to be XML escaped.
			-->
			<gpg.keyname>Firstname Lastname (Comment) &lt;user@email.org&gt;</gpg.keyname>
		</properties>
	</profile>
</profiles>

See the Sonatype guide for further details about how to work with GPG keys.

Prepare the release

# open a "private" shell, to not spill the changes in env vars
bash
# set env vars
export JAVA_HOME="${JAVA_6_HOME}"
export MAVEN_HOME="${MAVEN_3_2_5_HOME}"
export PATH="${MAVEN_HOME}/bin/:${PATH}"
# check if everything is in order
mvn \
	clean \
	package \
	verify \
	gpg:sign \
	site
mvn release:clean
mvn \
	-DdryRun=true \
	release:prepare
# run the prepare phase for real
mvn release:clean
mvn \
	-DdryRun=false \
	release:prepare
# leave our "private" shell instance again
exit

This does the following:

  • Important for backwards compatibility: use the oldest possible JDK version to compile (currently 1.6)
  • asks for the release and new snapshot versions to use (for all modules)
  • packages
  • signs with GPG
  • commits
  • tags

Perform the release (main part)

# open a "private" shell, to not spill the changes in env vars
bash
# set env vars
export JAVA_HOME="${JAVA_6_HOME}"
export MAVEN_HOME="${MAVEN_3_2_5_HOME}"
export PATH="${MAVEN_HOME}/bin/:${PATH}"
# perform the release
git push origin master <release-tag>
mvn release:perform
# leave our "private" shell instance again
exit

This does the following:

  • pushes to origin
  • checks-out the release tag
  • builds
  • deploy into Sonatype staging repository

Release the site

git checkout <release-tag>
mvn clean site
git checkout master

This does the following:

  • generates the site
  • pushes the site to the GitHub gh-pages branch, which is visible under http://hoijui.github.com/JavaOSC/

Promote it on Maven

Use one of these methods:

  • default: using the Nexus staging plugin

      mvn nexus:staging-close
      mvn nexus:staging-release
    
  • alternative: using the web-interface

    1. firefox https://oss.sonatype.org
    2. login
    3. got to the "Staging Repositories" tab
    4. select "com.illposed..."
    5. "Close" it
    6. select "com.illposed..." again
    7. "Release" it

This moves the artifact from the Sonatype staging to the main Sonatype repository. From there, it will automatically be copied to Maven Central, which happens at least every four hours.

Thanks

Thanks to John Thompson for writing the UI (demo application), Alexandre Quessy for the PD demo, and to Martin Kaltenbrunner and Alex Potsides for their contributions.