/
index.js
205 lines (195 loc) · 7.62 KB
/
index.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
(function() {
//~readme.out~
//[](http://travis-ci.org/russellmcc/node-osc-min) [](https://coveralls.io/r/russellmcc/node-osc-min?branch=master) [](https://david-dm.org/russellmcc/node-osc-min)
//# osc-min
//
// _simple utilities for open sound control in node.js_
//
// This package provides some node.js utilities for working with
// [OSC](http://opensoundcontrol.org/), a format for sound and systems control.
// Here we implement the [OSC 1.1][spec11] specification. OSC is a transport-independent
// protocol, so we don't provide any server objects, as you should be able to
// use OSC over any transport you like. The most common is probably udp, but tcp
// is not unheard of.
//
// [spec11]: http://opensoundcontrol.org/spec-1_1
//
//----
//## Installation
//~installation~
//----
//## Examples
//~examples~
//
// more examples are available in the `examples/` directory.
//
//----
//~api~
//----
//~representation~
//----
//## License
// Licensed under the terms found in COPYING (zlib license)
//~representation~
//## Javascript representations of the OSC types.
// See the [spec][spec] for more information on the OSC types.
//
// + An _OSC Packet_ is an _OSC Message_ or an _OSC Bundle_.
//
// + An _OSC Message_:
//
// {
// oscType : "message"
// address : "/address/pattern/might/have/wildcards"
// args : [arg1,arg2]
// }
//
// Where args is an array of _OSC Arguments_. `oscType` is optional.
// `args` can be a single element.
//
// + An _OSC Argument_ is represented as a javascript object with the following layout:
//
// {
// type : "string"
// value : "value"
// }
//
// Where the `type` is one of the following:
// + `string` - string value
// + `float` - numeric value
// + `integer` - numeric value
// + `blob` - node.js Buffer value
// + `true` - value is boolean true
// + `false` - value is boolean false
// + `null` - no value
// + `bang` - no value (this is the `I` type tag)
// + `timetag` - numeric value
// + `array` - array of _OSC Arguments_
//
// Note that `type` is always a string - i.e. `"true"` rather than `true`.
//
// The following non-standard types are also supported:
// + `double` - numeric value (encodes to a float64 value)
//
//
// For messages sent to the `toBuffer` function, `type` is optional.
// If the argument is not an object, it will be interpreted as either
// `string`, `float`, `array` or `blob`, depending on its javascript type
// (String, Number, Array, Buffer, respectively)
//
// + An _OSC Bundle_ is represented as a javascript object with the following fields:
//
// {
// oscType : "bundle"
// timetag : 7
// elements : [element1, element]
// }
//
// `oscType` "bundle"
//
// `timetag` is one of:
// - `null` - meaning now, the current time.
// By the time the bundle is received it will too late and depending
// on the receiver may be discarded or you may be scolded for being late.
// - `number` - relative seconds from now with millisecond accuracy.
// - `Date` - a JavaScript Date object in your local time zone.
// OSC timetags use UTC timezone, so do not try to adjust for timezones,
// this is not needed.
// - `Array` - `[numberOfSecondsSince1900, fractionalSeconds]`
// Both values are `number`s. This gives full timing accuracy of 1/(2^32) seconds.
//
// `elements` is an `Array` of either _OSC Message_ or _OSC Bundle_
//
//
// [spec]: http://opensoundcontrol.org/spec-1_0
var utils, coffee;
utils = require("./osc-utilities");
// ~api~
//## Exported functions
//
//------
//### .fromBuffer(buffer, [strict])
// takes a node.js Buffer of a complete _OSC Packet_ and
// outputs the javascript representation, or throws if the buffer is ill-formed.
//
// `strict` is an optional parameter that makes the function fail more often.
exports.fromBuffer = function(buffer, strict) {
if (buffer instanceof ArrayBuffer) {
buffer = new Buffer(new Uint8Array(buffer));
} else if (buffer instanceof Uint8Array) {
buffer = new Buffer(buffer);
}
return utils.fromOscPacket(buffer, strict);
};
//~api~
//----
//### .toBuffer(object, [strict])
// takes a _OSC packet_ javascript representation as defined below and returns
// a node.js Buffer, or throws if the representation is ill-formed.
//
// See "JavaScript representations of the OSC types" below.
//
//----
//### .toBuffer(address, args[], [strict])
// alternative syntax for above. Assumes this is an _OSC Message_ as defined below,
// and `args` is an array of _OSC Arguments_ or single _OSC Argument_
exports.toBuffer = function(object, strict, opt) {
if(typeof object === "string")
return utils.toOscPacket({'address' : object, 'args' : strict}, opt);
return utils.toOscPacket(object, strict);
};
//~api~
//----
//### .applyAddressTransform(buffer, transform)
// takes a callback that takes a string and outputs a string,
// and applies that to the address of the message encoded in the buffer,
// and outputs an encoded buffer.
//
// If the buffer encodes an _OSC Bundle_, this applies the function to each address
// in the bundle.
//
// There's two subtle reasons you'd want to use this function rather than
// composing `fromBuffer` and `toBuffer`:
// - Future-proofing - if the OSC message uses an argument typecode that
// we don't understand, calling `fromBuffer` will throw. The only time
// when `applyAddressTranform` might fail is if the address is malformed.
// - Accuracy - javascript represents numbers as 64-bit floats, so some
// OSC types will not be able to be represented accurately. If accuracy
// is important to you, then, you should never convert the OSC message to a
// javascript representation.
exports.applyAddressTransform = function(buffer, transform) {
return utils.applyTransform(buffer, utils.addressTransform(transform));
};
//~api~
//----
//### .applyMessageTransform(buffer, transform)
// takes a function that takes and returns a javascript _OSC Message_ representation,
// and applies that to each message encoded in the buffer,
// and outputs a new buffer with the new address.
//
// If the buffer encodes an osc-bundle, this applies the function to each message
// in the bundle.
//
// See notes above for applyAddressTransform for why you might want to use this.
// While this does parse and re-pack the messages, the bundle timetags are left
// in their accurate and prestine state.
exports.applyMessageTransform = function(buffer, transform) {
return utils.applyTransform(buffer, utils.messageTransform(transform));
};
//~api~
//----
//### .timetagToDate(ntpTimeTag)
// Convert a timetag array to a JavaScript Date object in your local timezone.
//
// Received OSC bundles converted with `fromBuffer` will have a timetag array:
// [secondsSince1970, fractionalSeconds]
// This utility is useful for logging. Accuracy is reduced to milliseconds.
exports.timetagToDate = utils.timetagToDate;
//~api~
//----
//### .dateToTimetag(date)
// Convert a JavaScript Date to a NTP timetag array [secondsSince1970, fractionalSeconds].
//
// `toBuffer` already accepts Dates for timetags so you might not need this function. If you need to schedule bundles with finer than millisecond accuracy then you could use this to help assemble the NTP array.
exports.dateToTimetag = utils.dateToTimetag;
}).call(this);