Permalink
Newer
Older
100644 246 lines (152 sloc) 10.1 KB
Aug 12, 2011
1
,~~~
2
+~~~~~
3
?~~~~+~
4
8~~~~~+~,
5
O~~~~~=+==
6
8?~~~~=+=~~
7
NI=~~~~~~~~~
8
DO?~~=7I~~~~=
9
Z8?~~~~~~:+~?$I, ,,,,,
10
ZNOI~~~~~~~~~~~.~7$$Z7:~~ZZZOSCZZ+,
11
ZDO7:~~~=~~~~~~~ $MZCSOZZ,~
12
ZDOOI~~?~~~~===== ~DZO7
13
~NDOO?~~~~~~~~~~~ ~7:$
14
:I OO$+~~~~==~~==~ ~? Z
15
DDDD8D?~~~~~~~====~ ~: I$
16
D DDDN8Z=~~~~~===~~~~ + I`
17
? DDDDN8O7~~~~~~~~====.7 $$
18
N888DNMOO?~~~~~===~~~$? .?
19
O88+DM ~NNN88OI~~~~~=~~~+~~?/$
20
D OVERTONE88I~~~~~===~~~,~
21
D ~ INC.NNN888I~~~~~=~~==,
22
:I ND~ DDN888O~~~?======,
23
8 8DDD ~ M88887:I~~=====
24
D 8DDDDND D 88$~~~===+z
25
:D8MDDDNN DD87~~I~+=
26
88DDDDDN DD7?~~
27
$CLOJURE DD`
28
$8DSDDDD
29
DDDCDDDN 888 d8b
30
::7OLIBRARY$$$77I$IZ7 888 Y8P
31
888
32
.d88b. .d8888b .d8888b .d8888b 888 8888
33
d88""88b 88K d88P" d88P" 888 "888
34
888 888 "Y8888b. 888 888888 888 888 888
35
Y88..88P X88 Y88b. Y88b. 888 888
36
"Y88P" 88888P' "Y8888P "Y8888P 888 888
37
888
38
d88P
39
888P"
40
41
42
43
# Open Sound Control Library for Clojure
44
45
A full-featured UDP-based OSC communication library created for Project Overtone. It implements OSC 1.0 with some additional types from 1.1 also supported (long and double). Find OSC documentation here:
46
47
http://opensoundcontrol.org/spec-1_0
48
Aug 12, 2011
49
50
## Quick Start
Feb 25, 2010
51
52
(use 'osc)
Aug 8, 2011
53
Feb 25, 2010
54
(def PORT 4242)
Aug 8, 2011
55
Feb 25, 2010
56
; start a server and create a client to talk with it
Aug 8, 2011
57
(def server (osc-server PORT))
Feb 25, 2010
58
(def client (osc-client "localhost" PORT))
Aug 8, 2011
59
Feb 25, 2010
60
; Register a handler function for the /test OSC address
61
; The handler takes a message map with the following keys:
62
; {:src-host, :src-port, :path, :type-tag, :args}
Aug 8, 2011
63
(osc-handle server "/test" (fn [msg] (println "MSG: " (:args msg))) :my-handler)
64
Feb 25, 2010
65
; send it some messages
66
(doseq [val (range 10)]
67
(osc-send client "/test" "i" val))
Aug 8, 2011
68
Feb 25, 2010
69
(Thread/sleep 1000)
Aug 8, 2011
70
71
;remove handler
72
(osc-rm-handler server "/test" :my-handler)
73
Feb 25, 2010
74
; stop listening and deallocate resources
75
(osc-close client)
76
(osc-close server)
77
Aug 12, 2011
78
## Documentation
79
80
### OSC Client
81
82
The `osc-clj` client allows you to send OSC messages to a server listening on a specific port on a specific host.
83
84
#### OSC Messages
85
86
OSC messages contain the following elements:
87
88
* A path (i.e. `/foo/bar/baz`)
89
* An arbitrary list of params (i.e. `2 "baz" 3.14159265 (byte-array 10)`
90
91
The supported param types are:
92
93
* Integers
94
* Floats
95
* Strings
96
* Byte Arrays
97
* Longs
98
* Doubles
99
100
You don't need to specify which type you are using, `osc-clj` will infer these with reflection.
101
102
Each message may or may not trigger a method handler to be executed on the receiving server - this is dependent on whether the path sent matches a registered handler on the server. Multiple handlers can be called by using regexp-like patterns in your out going path which may be matched to multiple handlers (see the pattern matching section below for more info).
103
104
#### Sending Messages
105
106
In order to send messages, you must first create a client withi `osc-client`:
107
108
(def client (osc-client "localhost" 9801))
109
110
Then you may send a message using `osc-send`:
111
112
(osc-send client "/foo/bar/baz 1 2 "three")
113
114
115
### OSC Server
116
117
The `osc-clj` server allows you to receive OSC messages by listening on a specific port. You may then register method handlers and/or listeners with the server which may be triggered by incoming messages.
118
119
Create new server with `osc-server`:
120
121
(def server (osc-server 9800))
122
123
#### OSC Listeners
124
125
`osc-clj` servers support both listeners and handlers. Listeners are fns you register which will be triggered for each and every incoming message. The fn must accept one argument - the message to receive. Each listener may also be associated with a unique key which allows you to individually remove it at a later time.
126
127
Here we use `osc-listen` to add a generic listener that will print *all* incoming OSC messages to std-out. We also specify the key `:debug`:
128
129
(osc-listen server (fn [msg] (println "Listener: " msg)) :debug)
130
131
To remove the listener simply call:
132
133
(osc-rm-listener server :debug)
134
135
`osc-clj` also supplies the fn `osc-rm-all-listeners` which will remove all listeners on the specified server.
136
137
#### OSC Method Handlers
138
139
Handlers are registered with an OSC path such as /foo/bar - they are only triggered if the path of the incoming OSC message matches the registered path.
140
141
To register a handler for the path "/foo/bar" do the following:
142
143
(osc-handle s "/foo/bar" (fn [msg] (println "Handler for /foo/bar: " msg)) :foo)
144
145
This will only print out received messages that match the path "/foo/bar". To remove call:
146
147
(osc-rm-handler s "/foo/bar" :foo)
148
149
`osc-clj` also supplies the fns `osc-rm-handlers` which will remove all the server's handlers on the specified path and `osc-rm-all-handlers` which will remove all the servers handlers within the path and below in the hierarchy (i.e. `(osc-rm-all-handlers server "/foo")` will remove all handlers registered at /foo and any below i.e. /foo/bar /foo/bar/baz etc. Passing no path to `osc-rm-all-handlers` will remove *all* handlers on the server.
150
151
### OSC Bundles
152
153
OSC bundles are groups of messages with a collective timestamp. This allows groups of messages to be scheduled to be handled at the same time which may be some arbitrary point in the future.
154
155
#### Receiving Bundles
156
157
When `osc-clj` receives a timestamped bundle it will schedule the bundle to be handled at the time of the timestamp. However, if the time is in the past, it will be handled immediately.
158
159
Handling the bundle means unpacking it and handling each contained message in sequence. Therefore, if a bundle contains another, and the inner bundle's timestamp is earlier than the outer bundle, it will *not* be honoured - instead it will trigger at the outer bundle's timestamp.
160
161
#### Sending Bundles
162
163
The simplest way to construct and send a bundle is with the macro `in-osc-bundle`. All OSC messages and bundles sent within the scope of the macro call will get sent together in the parent bundle with the specified timestamp:
164
165
Send the enclosing messages inside a bundle that is timestamped for 1 second from now:
Feb 25, 2010
166
167
(in-osc-bundle client (+ (osc-now) 1000)
Aug 12, 2011
168
(osc-send client "/foo" "bar" 42)
Aug 8, 2011
169
Feb 25, 2010
170
; Call functions that send more osc messages
171
(do-stuff client))
172
Aug 12, 2011
173
You can also create bundles by hand with `osc-bundle` and send them with `osc-send-bundle`. OSC messages can also be created with `osc-msg` in order to populate your bundle.
174
175
When constructing bundles, if you specify the timestamp with a Long, you can sample accurate messaging (with precision granularity around 200 picoseconds) for use with SuperCollider and other OSC servers. Bundles received with future timestamps are scheduled to be executed at that future time (with a precision granularity of around 10 milliseconds).
176
177
178
### Pattern Matching
179
180
`osc-clj` has full support for OSC pattern matching. This allows incoming messages to specify regexp like matcher symbols such as `?` and `*` allowing the message to match more than one path.
Aug 8, 2011
181
Aug 12, 2011
182
The basic matchers are:
Aug 8, 2011
183
Aug 15, 2011
184
* `*` Matches 0 or more arbitrary chars (`osc-clj` implements this in a non-greedy way)
Aug 12, 2011
185
* `?` Matches 1 arbitrary char
186
* `[abc]` Matches 1 char: either a, b or c
187
* `[!abc]` Matches 1 char: not a,b or c
188
* `[a-d]` Matches 1 char: in the range a-d inclusive `[!a-d]` is also recognised.
189
* `{foo,bar}` Matches 1 word - either foo or bar
Feb 25, 2010
190
Aug 12, 2011
191
192
The matchers may also be combined:
193
Aug 15, 2011
194
/foo/{bar,baz}/*/*quux?/[abc]def[!h]/phasor[0-9]/
Aug 12, 2011
195
196
There is no guarantee on the order of fn triggering.
197
198
For example, `/foo/{bar,baz}/quux` will trigger fns in both `/foo/bar/quux/` and `/foo/baz/quux` but with no specific order.
199
200
### Zeroconf
201
202
`osc-clj` has support for broadcasting the presence of your OSC servers to the local network using zerconf. This is disabled by default.
203
204
On creation of a server, you may specify an option tag:
205
206
(def server (osc-server 9800 "My OSC Server"))
207
Aug 15, 2011
208
The string `My OSC Server` is then used to register your server with zeroconf. In order to use zeroconf you must turn it on:
Aug 12, 2011
209
210
(zero-conf-on)
211
212
You should now see your server with clients that speak zeroconf. It is known that zero-conf can eat up a lot of cpu time - especially on chatty networks. It is therefore recommended to switch it off once you have configured and connected your client:
213
214
(zero-conf-off)
215
216
## Project Info:
218
Include in your project.clj like so:
219
Aug 15, 2011
220
[overtone/osc-clj "0.4.1"]
Aug 12, 2011
222
### Source Repository
223
Downloads and the source repository can be found on GitHub:
224
Aug 8, 2011
225
http://github.com/overtone/osc-clj
Aug 8, 2011
227
Eventually there will be more documentation for this library. In the
228
meantime we recommend you take a look at fns in the osc namespace and also see the library in use within the context of Project Overtone, located here:
Aug 8, 2011
230
http://github.com/overtone/overtone
Feb 25, 2010
232
Aug 12, 2011
233
### Mailing List
Aug 12, 2011
235
For any questions, comments or patches, use the Overtone google group:
236
237
http://groups.google.com/group/overtone
238
Aug 12, 2011
239
## Authors
240
241
* Jeff Rose
Aug 12, 2011
242
* Sam Aaron
243
244
### Contributors
245
* mw10013