_                       ____    _____   _____
     | |                     / __ \  / ____| / ____|
     | |  __ _ __   __ __ _ | |  | || (___  | |
 _   | | / _` |\ \ / // _` || |  | | \___ \ | |
| |__| || (_| | \ V /| (_| || |__| | ____) || |____
 \____/  \__,_|  \_/  \__,_| \____/ |_____/  \_____|

for branch master:

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.

• 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

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.

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.

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.

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

# open a "private" shell, to not spill the changes in env vars
bash
# set env vars
export JAVA_HOME="${JAVA_8_HOME}"
export MAVEN_HOME="${MAVEN_3_2_5_HOME}"
export PATH="${MAVEN_HOME}/bin/:${PATH}"
# do the release
mvn clean deploy
# leave our "private" shell instance again
exit

mvn release:clean

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;[email protected]&gt;</gpg.keyname>
		</properties>
	</profile>
</profiles>

If you have not yet done so, generate and publish a key-pair. See the Sonatype guide for further details about how to work with GPG keys.

# open a "private" shell, to not spill the changes in env vars
bash
# set env vars
export JAVA_HOME="${JAVA_8_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.8)
• asks for the release and new snapshot versions to use (for all modules)
• packages
• signs with GPG
• commits
• tags

# open a "private" shell, to not spill the changes in env vars
bash
# set env vars
export JAVA_HOME="${JAVA_8_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
mvn deploy -P release
# 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
• promote it on Maven Central repository (may have a delay of up to 4h)

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.