Module org.praxislive.internal.osc
Package org.praxislive.internal.osc

Class 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

      Fields 
      Modifier and Type Field Description
      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

      Constructors 
      Constructor Description
      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()

    • Field Detail

      • 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