|
class | OSCAddressSpace |
| OSCAddressSpace is the primary means of interacting with the OSC address space described in the OSC specification. This class is optional- it's not needed for basic OSC message sending/receiving. More...
|
|
class | OSCBundle |
| An OSCBundle is a "container" for multiple OSC messages or bundles (bundles may also be nested) More...
|
|
class | OSCInPort |
| OSCInPort handles everything needed to receive OSC data on a given port. More...
|
|
class | OSCManager |
| Main VVOSC class- manages in & out port creation, zero configuration networking (bonjour/zeroconf) More...
|
|
class | OSCMessage |
| Corresponds to an OSC message: contains zero or more values, and the address path the values have to get sent to. More...
|
|
protocol | <OSCNodeDelegateProtocol> |
| Delegates of OSCNode must respond to all three of these methods. More...
|
|
protocol | <OSCNodeQueryDelegate> |
| An OSCNode's queryDelegate must respond to these methods, which are called when a query-type OSCMessage is dispatched to an OSCNode. More...
|
|
class | OSCNode |
| OSCNode describes a single destination for OSC addresses. The OSC address space is made up of many different nodes. This class is optional- it is not used for basic OSC message sending/receiving, and only gets used if you start working with OSCAddressSpace. More...
|
|
class | OSCOutPort |
| OSCOutPort handles everything needed to send OSC data to a given address. More...
|
|
class | OSCPacket |
| Used to parse raw OSC data or to assemble raw OSC data from OSCMessages/OSCBundles. More...
|
|
class | OSCValue |
| OSCValue encapsulates any value you can send or receive via OSC. It is NOT mutable at this time. More...
|
|
|
enum | OSCValueType {
OSCValInt = 1,
OSCValFloat = 2,
OSCValString = 3,
OSCValTimeTag = 4,
OSCVal64Int = 5,
OSCValDouble = 6,
OSCValChar = 7,
OSCValColor = 8,
OSCValMIDI = 9,
OSCValBool = 10,
OSCValNil = 11,
OSCValInfinity = 12,
OSCValArray = 13,
OSCValBlob = 14,
OSCValSMPTE = 15
} |
| OSCValueType. More...
|
|
enum | OSCSMPTEFPS { ,
OSCSMPTEFPS24 = 1,
OSCSMPTEFPS25 = 2,
OSCSMPTEFPS30 = 3,
OSCSMPTEFPS48 = 4,
OSCSMPTEFPS50 = 5,
OSCSMPTEFPS60 = 6,
OSCSMPTEFPS120 = 7
} |
| OSCSMPTEFPS. More...
|
|
enum | OSCMIDIType {
OSCMIDINoteOffVal = 0x80,
OSCMIDINoteOnVal = 0x90,
OSCMIDIAfterTouchVal = 0xA0,
OSCMIDIControlChangeVal = 0xB0,
OSCMIDIProgramChangeVal = 0xC0,
OSCMIDIChannelPressureVal = 0xD0,
OSCMIDIPitchWheelVal = 0xE0,
OSCMIDIBeginSysexDumpVal = 0xF0,
OSCMIDIMTCQuarterFrameVal = 0xF1,
OSCMIDISongPosPointerVal = 0xF2,
OSCMIDISongSelectVal = 0xF3,
OSCMIDIUndefinedCommon1Val = 0xF4,
OSCMIDIUndefinedCommon2Val = 0xF5,
OSCMIDITuneRequestVal = 0xF6,
OSCMIDIEndSysexDumpVal = 0xF7,
OSCMIDIClockVal = 0xF8,
OSCMIDITickVal = 0xF9,
OSCMIDIStartVal = 0xFA,
OSCMIDIContinueVal = 0xFB,
OSCMIDIStopVal = 0xFC,
OSCMIDIUndefinedRealtime1Val = 0xFD,
OSCMIDIActiveSenseVal = 0xFE,
OSCMIDIResetVal = 0xFF
} |
| OSCMIDIType. More...
|
|
enum | OSCNodeType { OSCNodeTypeUnknown,
OSCNodeDirectory,
OSCNodeTypeNumber,
OSCNodeType2DPoint
} |
| OSCNodeType. More...
|
|
enum | OSCMessageType {
OSCMessageTypeUnknown =0,
OSCMessageTypeControl,
OSCMessageTypeQuery,
OSCMessageTypeReply,
OSCMessageTypeError
} |
| OSCMessageType. More...
|
|
enum | OSCQueryType {
OSCQueryTypeUnknown =0,
OSCQueryTypeNamespaceExploration,
OSCQueryTypeDocumentation,
OSCQueryTypeTypeSignature,
OSCQueryTypeCurrentValue,
OSCQueryTypeReturnTypeSignature
} |
| OSCQueryType. More...
|
|
Introduction
VVOSC is an Objective-c framework for assembling, sending, and receiving OSC (Open Sound Control) messages on OS X. A simple sample application (gui) which sends and receives OSC messages is also included to aid in the debugging of your software. There's also an SDK which allows you to develop iPhone applications which use VVOSC. All the source code is available on the project homepage: https://github.com/mrRay/vvopensource
Features and Capabilities
Includes a sample GUI app for debugging OSC applications and hardware that also demonstrates use of the framework
Packet parsing (client) + construction (server)
Creates bundles/nested bundles, safely parse bundles/nested bundles
Detects other OSC destinations via bonjour/zero-conf networking and automatically creates output ports so you can send data to them.
Input ports automagically advertise their presence via bonjour/zero-conf networking. This is as close to no-setup as it gets!
Supports the following data types: i (int32), f (float32), s/S (OSC-string), b (OSC blob), h (64-bit int), d (64-bit float/double), r (32-bit RGBA color), m (MIDI message), T (tru), F (false), N(nil), I (infinity), t (OSC-timetag)
Processing frequency defaults to 100hz, but may be adjusted dynamically and has been tested up to 1khz
Multithreaded- each input port runs on its own thread- and threadsafe.
Optional OSC address space classes (OSCNode & OSCAddressSpace) may be used to quickly and easily construct a threadsafe address space for controlling your software. Address space includes POSIX regex-based pattern matching for dispatching a single message to multiple addresses.
Native support for an experimental query protocol described here: (http://opensoundcontrol.org/publication/query-system-open-sound-control). The API for this protocol supports both blocks and delegate/callbacks for easy asynchronous OSC communication.
Built on a handful of small, easy-to-grok classes written specifically for OS X. Very easy to understand, modify, subclass, or extend.
Project includes targets that build and install an SDK for using VVOSC in iOS apps
Breaks from the OSC specification
"char" data type not supported yet, you can use "string" in the meantime.
It's possible to create an OSCValue from an NSString containing UTF8 characters, which VVOSC will try to send- and if the software receiving this data doesn't freak out, this allows you to UTF8 characters. In other words, VVOSC doesn't explicitly prevent the use of non-ASCII characters, so it's possible to use it to create incompatible OSC data!
The OSC specification describes a limited subset of regex to be used in wildcard/pattern matching for OSC dispatch. VVOSC's message dispatch is presently a POSIX regex engine simply because it was faster and easier to get going (it's built into the OS) than rolling my own. The specific engine used may change if message dispatch becomes a speed issue in the future; presumably, this ambiguity is why the OSC spec describes a specific and limited subset of regex!
The OSC spec describes the optional type characters [ and ] to delineate arrays and basic node-based structures for ad-hoc data types. Support for arrays has been added, but lacking any published examples of dictionaries, this isn't supported yet- if someone wants to send me a specific example i can use to support this protocol properly, please let me know!
While VVOSC parses, stores, and allows you to set OSC time tags (and even create and pass time tags as values), it doesn't perform any delay or scheduling if it receives an OSC bundle with a time tag which is later than the current time. Parsed time tags are available to your applications as the 'timeTag' variable of a passed OSCMessage, which is stored as an NSDate (which, internally, is a double which basically represents 64-bit NTP time, as I understand it).
VVOSC supports an experimental OSC query protocol described here: http://opensoundcontrol.org/publication/query-system-open-sound-control. This protocol isn't part of the official OSC specifical, and you shouldn't expect other apps to support it.
Sample code- Getting Started
// create an OSCManager- set myself up as its delegate
manager = [[OSCManager alloc] init];
[manager setDelegate:self];
// create an input port for receiving OSC data
[manager createNewInputForPort:1234];
// create an output so i can send OSC data to myself
outPort = [manager createNewOutputToAddress:@"127.0.0.1" atPort:1234];
// make an OSC message
newMsg = [OSCMessage createWithAddress:@"/Address/Path/1"];
// add a bunch arguments to the message
[newMsg addInt:12];
[newMsg addFloat:12.34];
[newMsg addColor:[NSColor colorWithDeviceRed:0.0 green:1.0 blue:0.0 alpha:1.0]];
[newMsg addBOOL:YES];
[newMsg addString:@"Hello World!"];
// send the OSC message
[outPort sendThisMessage:newMsg];
Sample code- the OSC Address Space (optional)
// get the OSC address space
OSCAddressSpace *as = [OSCAddressSpace mainAddressSpace];
// find/create a node in the address space
OSCNode *myNode = [as findNodeForAddress:@"/A/B/C" createIfMissing:YES];
// add myself to the node's delegates so i get informed of data passed to the node
[myNode setDelegate:self];
- (void) node:(id)n receivedOSCMessage:(OSCMessage *)msg {
// this method is called whenever the node receives OSC data because I'm one of the node's delegates
}
// dispatch an OSC message received from an OSCInPort to the address space
[as dispatchMessage:receivedMessage];
Sample code- OSC query protocol, sending queries (optional)
// assemble the query message
OSCMessage *queryMsg = [OSCMessage createQueryType:OSCQueryTypeNamespaceExploration forAddress:@"/"];
// dispatch the query to your chosen out port via the OSC manager- this example uses a block
[oscManager
dispatchQuery:queryMsg
toOutPort:targetOutPort
timeout:1.0
replyHandler:^(OSCMessage *replyMsg) {
// the code in here is executed when a reply is received (or the timeout has passed)
}];
// here's another way to dispatch a query, using a more old-fashioned delegate
[oscManager
dispatchQuery:queryMsg
toOutPort:targetOutPort
timeout:1.0
replyDelegate:self];
- (void) oscQueryReplyReceived:(OSCMessage *)replyMsg {
// this method is called when a reply is received or the timeout passes
}
Sample code- OSC query protocol, responding to queries (optional)
// get the OSC address space
OSCAddressSpace *as = [OSCAddressSpace mainAddressSpace];
// create a node in the address space
OSCNode *myNode = [as findNodeForAddress:@"/A/B/C" createIfMissing:YES];
// set 'autoQueryReply' to YES and the OSCNode instance will automatically generate replies to received queries
[myNode setAutoQueryReply:YES];
// for more precise control, you can set the node's queryDelegate to generate customized responses to specific queries
[myNode setQueryDelegate:self];
- (NSMutableArray *) namespaceArrayForNode:(id)n {
// this and other methods in the OSCNodeQueryDelegate protocol are called on the queryDelegate when the node receives queries
}