oscpack

News

April 9, 2013. Oscpack 1.1.0 is now available. Read the CHANGES file for more info.

January 13, 2013. I’m working on a refresh of oscpack and oscgroups. Please get in touch if you have patches to contribute or you’re available to help test building on different distros (wanted: all flavours of Linux, gcc on Windows, OSX 10.8, other Unix).

Browse the source code here. Interesting files in the repository are: README and CHANGES. See below for SVN access details and a downloadable zip file of the release.

Overview

Oscpack is simply a set of C++ classes for packing and unpacking OSC packets. Oscpack includes a minimal set of UDP networking classes for Windows and POSIX. The networking classes are sufficient for writing many OSC applications and servers, but you are encouraged to use another networking framework if it better suits your needs. Oscpack is not an OSC application framework. It doesn’t include infrastructure for constructing or routing OSC namespaces, just classes for easily constructing, sending, receiving and parsing OSC packets. The library should also be easy to use for other transport methods (e.g. serial).

The key goals of the oscpack library are:

  • Be a simple and complete implementation of OSC
  • Be portable to a wide variety of platforms
  • Allow easy development of robust OSC applications (for example it should be impossible to crash a server by sending it malformed packets, and difficult to create malformed packets.)

Status

Oscpack is stable and has been quite well tested in various applications across Windows, Linux and Mac OS X.

Suggestions for improvements to both the C++ interfaces and implementation are always welcome. It is possible that TCP networking classes will be added in the future.

Supported platforms

Oscpack has been compiled and used on Windows, Mac OS X and Linux. The latest version (1.1.0 at the time of writing) has been tested on 64 bit platforms.

Availability

Oscpack is now hosted in an SVN repository at googlecode. Instructions for performing an SVN checkout are here: code.google.com/p/oscpack/source/checkout

Download snapshots

For your convenience, zip file snapshots of the repository are available for download here.

Current stable release, version 1.1.0 : oscpack_1_1_0

Older snapshots (not recommended), may be required to compile some existing projects. The file name format is year_month_day_hourminute.

Examples

More extensive examples are provided in the source distribution, but the following should give you a taste of what to expect.

// formatting messages into a packet for sending:
    UdpTransmitSocket transmitSocket( IpEndpointName( ADDRESS, PORT ) );

    char buffer[OUTPUT_BUFFER_SIZE];
    osc::OutboundPacketStream p( buffer, OUTPUT_BUFFER_SIZE );

    p << osc::BeginBundleImmediate
        << osc::BeginMessage( "/test1" )
            << true << 23 << (float)3.1415 << "hello" << osc::EndMessage
        << osc::BeginMessage( "/test2" )
            << true << 24 << (float)10.8 << "world" << osc::EndMessage
        << osc::EndBundle;
	transmitSocket.Send( p.Data(), p.Size() );
// processing incoming messages
class ExamplePacketListener : public osc::OscPacketListener {
protected:
	virtual void ProcessMessage( const osc::ReceivedMessage& m,
		const IpEndpointName& remoteEndpoint )
	{
		try{
			// example of parsing single messages. osc::OscPacketListener
			// handles the bundle traversal.
			if( strcmp( m.AddressPattern(), "/test1" ) == 0 ){
				// example #1 -- argument stream interface
				osc::ReceivedMessageArgumentStream args = m.ArgumentStream();
				bool a1;
				osc::int32 a2;
				float a3;
				const char *a4;
				args >> a1 >> a2 >> a3 >> a4 >> osc::EndMessage;

                std::cout << "received '/test1' message with arguments: "
                    << a1 << " " << a2 << " " << a3 << " " << a4 << "\n";                              

			}else if( strcmp( m.AddressPattern(), "/test2" ) == 0 ){
				// example #2 -- argument iterator interface, supports
				// reflection for overloaded messages (eg you can call
				// (*arg)->IsBool() to check if a bool was passed etc).

                osc::ReceivedMessage::const_iterator arg = m.ArgumentsBegin();
                bool a1 = (arg++)->AsBool();
                int a2 = (arg++)->AsInt32();
                float a3 = (arg++)->AsFloat();
                const char *a4 = (arg++)->AsString();
                if( arg != m.ArgumentsEnd() )
                    throw osc::ExcessArgumentException();

                std::cout << "received '/test2' message with arguments: "
                    << a1 << " " << a2 << " " << a3 << " " << a4 << "\n";
            }
        }catch( osc::Exception& e ){
            // any parsing errors such as unexpected argument types, or
            // missing arguments get thrown as exceptions.
            std::cout << "error while parsing message: "
                << m.AddressPattern() << ": " << e.what() << "\n";
        }
    }
};

History

The original design for oscpack arose after reading the SuperCollider server source code and deciding that a similar OSC implementation with a BSD-style license was needed. The first public release of oscpack came about because we needed an OSC library for the reacTable project, and the other OSC libraries which were reviewed (Berkeley OSC, liblo, libosc++) either were not very C++ oriented, or were not easy to port to Windows. Although the packet manipulation classes have survived virtually unchanged since the first public release in 2004, the networking code has been rewritten to meet the more advanced requirements of oscgroups.

See also

For more information about Open Sound Control, go to opensoundcontrol.org.

Acknowledgements

Thanks to Till Bovermann for helping with POSIX networking code and Mac compatibility, and to Martin Kaltenbrunner and the rest of the reacTable team for giving me a reason to finish this library. Thanks to Merlijn Blaauw for reviewing the interfaces. Thanks to Xavier Oliver for additional help with Linux builds and POSIX implementation details.

Portions developed at the Music Technology Group, Audiovisual Institute, University Pompeu Fabra, Barcelona, during my stay as a visiting researcher, November 2004 – September 2005.

Thanks to Syneme at the University of Calgary for providing financial support for the 1.1.0 update.

Terms of use

Oscpack is distributed under the MIT open source license:

Copyright © 2004-2013 Ross Bencina

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The text above constitutes the entire oscpack license; however,  the oscpack developer(s) also make the following non-binding requests: Any person wishing to distribute modifications to the Software is requested to send the modifications to the original developer so that they can be incorporated into the canonical version. It is also  requested that these non-binding requests be included whenever the above license is reproduced.

All feedback welcome. Please feel free to email comments to Ross at rossb@audiomulch.com