Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/hoijui/javaosc
OSC content format/"protocol" library for JVM languages
https://github.com/hoijui/javaosc
content-format java java-8 library open-sound-control osc osgi-bundle protocol
Last synced: 5 days ago
JSON representation
OSC content format/"protocol" library for JVM languages
- Host: GitHub
- URL: https://github.com/hoijui/javaosc
- Owner: hoijui
- License: bsd-3-clause
- Created: 2012-02-10T12:54:00.000Z (almost 13 years ago)
- Default Branch: master
- Last Pushed: 2024-12-30T17:59:19.000Z (19 days ago)
- Last Synced: 2025-01-12T22:02:48.456Z (5 days ago)
- Topics: content-format, java, java-8, library, open-sound-control, osc, osgi-bundle, protocol
- Language: Java
- Homepage: http://www.illposed.com/software/javaosc.html
- Size: 1.56 MB
- Stars: 159
- Watchers: 21
- Forks: 44
- Open Issues: 17
-
Metadata Files:
- Readme: README.markdown
- License: LICENSE.md
Awesome Lists containing this project
README
```text
_ ____ _____ _____
| | / __ \ / ____| / ____|
| | __ _ __ __ __ _ | | | || (___ | |
_ | | / _` |\ \ / // _` || | | | \___ \ | |
| |__| || (_| | \ V /| (_| || |__| | ____) || |____
\____/ \__,_| \_/ \__,_| \____/ |_____/ \_____|
```
## Status
[](
https://github.com/hoijui/JavaOSC/blob/master/LICENSE)
[](
https://maven-badges.herokuapp.com/maven-central/com.illposed.osc/javaosc-core/)
[](
https://github.com/hoijui/JavaOSC/issues)
[](
irc://irc.freenode.net/javaosc)
[](
https://api.reuse.software/info/github.com/hoijui/JavaOSC)
[](
https://github.com/hoijui/JavaOSC)
[](
https://travis-ci.org/hoijui/JavaOSC?branch=master)
[](
https://lgtm.com/projects/g/hoijui/JavaOSC/context:java)
[](
https://lgtm.com/projects/g/hoijui/JavaOSC/alerts/)
[](
https://sonarcloud.io/dashboard?id=com.illposed.osc:javaosc)
[](
https://sonarcloud.io/component_measures/metric/coverage/list?id=com.illposed.osc:javaosc)
[](
https://sonarcloud.io/component_measures/metric/reliability_rating/list?id=com.illposed.osc:javaosc)
[](
https://sonarcloud.io/component_measures/metric/security_rating/list?id=com.illposed.osc:javaosc)
## What is this?
### JavaOSC
JavaOSC is primarily a library that gives JVM language programs the ability
of serializing, parsing, sending and receiving data in the OSC content format.
It is written in Java 8, and its only runtime dependency is a logging facade (_SLF4J_).
It is also an [OSGi](https://www.osgi.org/developer/what-is-osgi/)
(a dynamic module system for Java) bundle.
In a separate package,
it also contains a sample GUI that allows to send OSC messages to SuperCollider.
### Open Sound Control (OSC)
is a simple _content format_,
although it is often though of as a _protocol_
for the transmission of data over a network.
#### Application domains
* as a **replacement for MIDI** -
a network-protocol for the exchange of musical control data between soft- and hardware,
usually over a UDP/IP network
* in **robotics** -
for communication between the parts of a robot,
or multiple robots amongst each other
Its main strength is its simplicity.
## How to
### Get it
The latest release version of the library is available on
[GitHub for manual download](https://github.com/hoijui/JavaOSC/releases)
or on
[Maven central](https://search.maven.org/search?q=a:javaosc-core)
```xml
com.illposed.osc
javaosc-core
0.8
```
The latest development sources can be found
[on GithHub](https://github.com/hoijui/JavaOSC).
### 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 for demonstration purposes.
To _run the demo app_, make sure you have all parts packaged and installed:
```bash
mvn install
```
Then start the UI:
```bash
cd modules/ui
mvn exec:java
```
Next, launch SuperCollider (SC), 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](http://www.sourcelibre.com/puredata/).
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.
### Run the OSH Echo Server
This tool simple listens on `0.0.0.0`,
and returns every OSC message it gets, as-is.
Before running -
and every time the sources change -
run this once:
```bash
mvn install
```
Then to run, simply execute:
```bash
mvn --projects modules/cmds exec:java
```
### 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.transport.OSCPort{In, Out}`,
`com.illposed.osc.OSCMessage` and `com.illposed.osc.OSCBundle`.
The common way to use the library is to instantiate an `OSCPort{In, Out}`
connected to the receiving machine, and then call `port.send(myPacket)`.
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)
To release a development version to the Sonatype snapshot repository only:
```bash
# open a "private" shell, to not spill the changes in env vars
bash
# set env vars
export JAVA_HOME="${JAVA_8_HOME}"
# do the release
mvn clean deploy
# leave our "private" shell instance again
exit
```
In the project you want to use the _SNAPSHOT_ release,
you need to add this to your _pom.xml_:
```xml
ossrh
https://oss.sonatype.org/content/repositories/snapshots
```
## Release (devs only)
### Prepare "target/" for the release process
```bash
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:
```xml
ossrh
true
gpg2
Firstname Lastname (Comment) <[email protected]>
```
If you have not yet done so, generate and publish a key-pair.
See [the Sonatype guide](http://central.sonatype.org/pages/working-with-pgp-signatures.html)
for further details about how to work with GPG keys.
### Prepare the release
```bash
# open a "private" shell, to not spill the changes in env vars
bash
# set env vars
export JAVA_HOME="${JAVA_8_HOME}"
# 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
### Perform the release (main part)
```bash
# open a "private" shell, to not spill the changes in env vars
bash
# set env vars
export JAVA_HOME="${JAVA_8_HOME}"
# perform the release
git push origin master --tags
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
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.