de.sciss.net
Class OSCBundle

java.lang.Object
  de.sciss.net.OSCPacket
      de.sciss.net.OSCBundle

public class OSCBundle
extends OSCPacket

Implementation of the OSC-Bundle which assembles several OSC-Packets under the same timetag. See opensoundcontrol.org/spec-1_0 for the specification of the bundle format.

The bundle time can be calculated in different ways: specifying a long which represents the milliseconds since 1 jan 1970 as returned by System.currentTimeMillis(), produces the required network time tag as required by the OSC specification. Alternatively, using a float for a relative time offset in seconds can be used when running SuperCollider in offline mode. Third, there is a version that calculates a sample accurate time tag. However, scsynth doesn't process bundles with this accuracy, so it's kind of useless.

To assemble a bundle, you create a new instance of OSCBundle, call addPacket one or several times, then write the contents of the bundle to a ByteBuffer using the method encode. The byte buffer can then be written to a DatagramChannel. Here is an example:

      OSCBundle       bndl;
      DatagramChannel dch = null;

      final ByteBuffer buf        = ByteBuffer.allocateDirect( 1024 );
      final SocketAddress addr    = new InetSocketAddress( "localhost", 57110 );
      final long serverLatency    = 50;
      final long now              = System.currentTimeMillis() + serverLatency;

      try {
          dch = DatagramChannel.open();
          dch.configureBlocking( true );
          bndl = new OSCBundle( now );
          bndl.addPacket( new OSCMessage( "/s_new", new Object[] { "default",
                          new Integer( 1001 ), new Integer( 1 ), new Integer( 0 ),
                          "out", new Integer( 0 ), "freq", new Float( 666 ), "amp", new Float( 0.1f )}));
          bndl.encode( buf );
          buf.flip();
          dch.send( buf, addr );
          buf.clear();
          bndl = new OSCBundle( now + 2000 ); // two seconds later
          bndl.addPacket( new OSCMessage( "/n_free", new Object[] { new Integer( 1001 )}));
          bndl.encode( buf );
          buf.flip();
          dch.send( buf, addr );
      }
      catch( IOException e2 ) {
          System.err.println( e2.getLocalizedMessage() );
      }
      finally {
          if( dch != null ) {
              try {
                  dch.close();
              }
              catch( IOException e4 ) {};
          }
      }
        

Note that this example uses the old way of sending messages. A easier way is to create an OSCTransmitter which handles the byte buffer for you. See the OSCReceiver doc for an example using a dedicated transmitter.

Version:

0.33, 28-Apr-07

Author:

Hanns Holger Rutz

See Also:

OSCReceiver

Field Summary

protected List	collPackets
static long	NOW The special timetag value to indicate that the bundle be processed as soon as possible
static String	TAG This is the initial string of an OSC bundle datagram

Constructor Summary

OSCBundle()
Creates a new empty OSCBundle with timetag set to "immediately".

OSCBundle(double when)
Creates a new empty OSCBundle with timetag specified by 'when' which is seconds relative to start of session.

OSCBundle(long when)
Creates a new empty OSCBundle with timetag specified by 'when' which is milliseconds since 1 jan 1970 as returned by System.currentTimeMillis().

OSCBundle(long absMillisOffset, long sampleFrames, int sampleRate)
Creates a new empty OSCBundle with timetag specified by a sample frame offset and an absolute time in milliseconds since 1 jan 1970 as returned by System.currentTimeMillis()

Method Summary

void	addPacket(OSCPacket p) Adds a new OSCPacket to the tail of the bundle.
OSCPacket	getPacket(int idx) Gets the OSCPacket at the provided index which must be between 0 inclusive and getPacketCount() exclusive.
int	getPacketCount() Returns the number of packets currently assembled in this bundle.
long	getTimeTag() Returns the raw format time tag of the bundle
void	removePacket(int idx) Removes the specified packet
void	setTimeTagAbsMillis(long when) Sets the bundle's timetag specified by a long which is milliseconds since 1 jan 1970 as returned by System.currentTimeMillis().
void	setTimeTagRaw(long raw)
void	setTimeTagRelSecs(double when) Sets the bundle's timetag specified by a double which is seconds relative to start of session.
void	setTimeTagSamples(long absMillisOffset, long sampleFrames, int sampleRate) Sets the bundle's timetag as a combination of system absolute time and sample offset.

Methods inherited from class de.sciss.net.OSCPacket

decode, encode, encode, getSize, getSize, printHexOn, printTextOn

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TAG

public static final String TAG

This is the initial string of an OSC bundle datagram

See Also:

Constant Field Values

NOW

public static final long NOW

The special timetag value to indicate that the bundle be processed as soon as possible

See Also:

Constant Field Values

collPackets

protected final List collPackets

Constructor Detail

OSCBundle

public OSCBundle()

Creates a new empty OSCBundle with timetag set to "immediately". SuperCollider recognizes this special timetime to process the bundle just when it arrives.

OSCBundle

public OSCBundle(long when)

Creates a new empty OSCBundle with timetag specified by 'when' which is milliseconds since 1 jan 1970 as returned by System.currentTimeMillis(). This is converted into an absolute time offset since 1 jan 1900 as required by the OSC specs.

Parameters:

when - absolute time tag for the bundle

See Also:

System.currentTimeMillis()

OSCBundle

public OSCBundle(double when)

Creates a new empty OSCBundle with timetag specified by 'when' which is seconds relative to start of session. This relative time offset with origin of zero is understood by SuperCollider in NonRealTime mode. (see example in Non-Realtime-Synthesis.rtf).

Parameters:

when - relative time tag for the bundle

OSCBundle

public OSCBundle(long absMillisOffset,
                 long sampleFrames,
                 int sampleRate)

Creates a new empty OSCBundle with timetag specified by a sample frame offset and an absolute time in milliseconds since 1 jan 1970 as returned by System.currentTimeMillis()

Parameters:

absMillisOffset - time offset as returned by System.currentTimeMillis

sampleFrames - this offset is added to the milli second offset.

sampleRate - used in conjunction with sampleFrames to calculate the time offset.

Method Detail

addPacket

public void addPacket(OSCPacket p)

Adds a new OSCPacket to the tail of the bundle. Passing null is allowed in which case no action is performed.

Parameters:

p - the packet to add to the tail of the bundle

getPacket

public OSCPacket getPacket(int idx)

Gets the OSCPacket at the provided index which must be between 0 inclusive and getPacketCount() exclusive. If bundles are nested, each nested bundle will count as one packet of course.

Parameters:

idx - index of the packet to get

Returns:

packet at index idx

getPacketCount

public int getPacketCount()

Returns the number of packets currently assembled in this bundle. If bundles are nested, each nested bundle will count as one packet of course.

Returns:

number of packets assembled in this bundle

removePacket

public void removePacket(int idx)

Removes the specified packet

Parameters:

idx - the index of the packet to remove

setTimeTagAbsMillis

public void setTimeTagAbsMillis(long when)

Sets the bundle's timetag specified by a long which is milliseconds since 1 jan 1970 as returned by System.currentTimeMillis(). This is converted into an absolute time offset since 1 jan 1900 as required by the OSC specs.

Parameters:

when - absolute time tag for the bundle

See Also:

System.currentTimeMillis()

setTimeTagRaw

public void setTimeTagRaw(long raw)

setTimeTagRelSecs

public void setTimeTagRelSecs(double when)

Sets the bundle's timetag specified by a double which is seconds relative to start of session. This relative time offset with origin of zero is understood by SuperCollider in NonRealTime mode. (see example in Non-Realtime-Synthesis.rtf).

Parameters:

when - relative time tag for the bundle

setTimeTagSamples

public void setTimeTagSamples(long absMillisOffset,
                              long sampleFrames,
                              int sampleRate)

Sets the bundle's timetag as a combination of system absolute time and sample offset. note that this is not too useful, because supercollider will execute OSC bundles not with audiorate but controlrate precision!!

Parameters:

absMillisOffset - time offset as returned by System.currentTimeMillis

sampleFrames - this offset is added to the milli second offset.

sampleRate - used in conjunction with sampleFrames to calculate the time offset.

getTimeTag

public long getTimeTag()

Returns the raw format time tag of the bundle

Returns:

the bundle's timetag in OSC format

Todo:

a utility method to convert this to a more useful value