Ross Bencina
home page
email
Page last updated 21 November 2006
November 21, 2006. Oscpack 1.0.2 has been released. This is a roll-up of a number of small patches comitted to SVN over the last year. The main changes are (1) improved support for 64-bit operation (removed some non-portable casts) and (2) support for non-standard Super Collider integer address patterns.
Interesting files in the repository are: README and CHANGES. Browse the source code here. See below for SVN access details and a downloadable zip file of the release.
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 which 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 (eg serial).
The key goals of the oscpack library are:
The original design for oscpack arose after reading the supercollider server source code and deciding that a similar OSC implementation could be useful for AudioMulch. However supercollider is licensed under the GPL so its code couldn't be used in the closed-source AudioMulch program, a library 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 recently been rewritten to meet the more advanced requirements of oscgroups.
Oscpack is stable and has been quite well tested in various applications accross Windows, Linux and Mac OS X.
The library is currently used in the author's AudioMulch software and oscgroups, by a number of applications at the Music Technology Group, Universitat Pompeu Fabra, including the reacTable, and CLAM, and Rémy Muller's OSCmap. If you use oscpack in your project, please let me know.
Suggestions for improvements to both the C++ interfaces and implementation are always welcome. We are currently looking for a simple way to make the Makefile autodetect that it is running on Mac OS. It is possible that TCP networking classes will be added in the future.
Oscpack has been compiled and used on Windows, Mac OS X and Linux. It should also work on 64 bit platforms, although this has not yet been tested.
Oscpack is now hosted in a Subversion (SVN) repository at smartelectronix (thanks to Bram and Nessie!). You can browse the source code with your web browser at the following URL:
http://ross.smartelectronix.com/index.cgi/browser/oscpack/
You can access the SVN repository using an SVN client (anonymous read access available) at:
https://www.smartelectronix.com:9000/repos/osc/
For your convenience, snapshots of the repository are available for download here.
Latest stable release, version 1.0.2: oscpack_1_0_2.zip
Previous stable release, version 1.0.1: oscpack_1_0_1.zip
Older snapshots, may be required to compile some exisiting projects. The filename format is year_month_day_hourminute.
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";
}
}
};
For more information about Open Sound Control, see the Open Sound Control home page.
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.
Oscpack is distributed under the following BSD style open source license: