The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-OpenSoundControl-0.05
River stage zero No dependents
++
/ Net::OpenSoundControl

NAME

Net::OpenSoundControl - OpenSound Control client and server implementation

SYNOPSIS

See Net::OpenSoundControl::Client and Net::OpenSoundControl::Server for the synopsis.

DESCRIPTION

    OpenSound Control ("OSC") is a protocol for communication among computers,
    sound synthesizers, and other multimedia devices that is optimized for
    modern networking technology. 

    http://www.cnmat.berkeley.edu/OpenSoundControl

This suite of modules provides an implementation of the protocol in Perl, according to version 1.0 (March 26, 2002) of the specification.

To actually create an OSC client or server, take a look at Net::OpenSoundControl::Client and Net::OpenSoundControl::Server. This module only provides several helper functions. Normally, there shouldn't be a need for you to use this module directly.

Please also see the examples/ directory in this distribution, especially if you are not very familiar with references.

DATA FORMAT

OSC data is represented in a form closely related to the original binary format.

MESSAGES

A message is an array reference containing an OSC address followed by zero or more pairs of type identifiers and data. Examples:

    ['/Fader', f, 0.2]

    ['/Synth/XY', i, 10, i, 200]

BUNDLES

A bundle is an array reference that contains the bundle identifier #bundle and a timestamp, followed by zero or more messages. Examples:

    ['#bundle', time() + 0.1, ['/Pitch', 'f', rand(1)]

    ['#bundle', time() + 2, ['/Slider', 'f', $s],
                            ['/Synth/XY', 'i', $x, 'i', $y]

Note that the time should be expressed in seconds since 1st January 1970, which is what time() returns on UNIX systems. You can pass it a floating point time, the Time::HiRes module will help you find the current time with sub-second accuracy.

A timestamp with the value "0" carries the special meaning of "execute immediately". Example:

    ['#bundle', 0, ['/Pitch', 'f', rand(1)]

FUNCTIONS

protocol()

Returns information about the version of the OSC protocol implemented. Currently OSC/1.0.

types()

Returns information about the data types implemented. Currently bfis (blobs, floats, ints and strings).

decode($data)

Decodes binary OSC message or bundle data into a Perl data structure

encode($data)

Encodes OSC messages or bundles into their binary representation

toInt($n)

Returns the binary representation of an integer in OSC format

fromFloat($n)

Converts the binary representation of a floating point value in OSC format into a Perl value. (There are no other "from..." functions since the code for that is directly embedded into the decode functons for speed, but this one is separate since it depends on the endianness of the system it's running on).

toFloat($n)

Returns the binary representation of a floating point value in OSC format

toString($str)

Returns the binary representation of a string in OSC format

toBlob($d)

Returns the binary representation of a BLOB value in OSC format

toTimetag($d)

Returns the binary representation of a TIMETAG value in OSC format.

BUGS

Doesn't work with Unicode data. Remember to use bytes if you use Unicode Strings.

SEE ALSO

Hacking Perl in Nightclubs at http://www.perl.com/pub/a/2004/08/31/livecode.html

The OpenSoundControl website at http://www.cnmat.berkeley.edu/OpenSoundControl/

Net::OpenSoundControl::Client

Net::OpenSoundControl::Server

AUTHOR

Christian Renz, <crenz @ web42.com>

Timestamp code lifted from Net::NTP.

Test against specification by Alex (yaxu.org).

COPYRIGHT AND LICENSE

Copyright 2004-2005 by Christian Renz <crenz @ web42.com>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.