Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 246 lines (152 sloc) 10.344 kB
c090837 @samaaron update README
samaaron authored
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:
d596dc0 @rosejn Initial creation of osc submodule.
rosejn authored
46
47 http://opensoundcontrol.org/spec-1_0
48
c090837 @samaaron update README
samaaron authored
49
50 ## Quick Start
f050e2d @rosejn adding more docs
rosejn authored
51
52 (use 'osc)
d1b92a0 @samaaron update readme
samaaron authored
53
f050e2d @rosejn adding more docs
rosejn authored
54 (def PORT 4242)
d1b92a0 @samaaron update readme
samaaron authored
55
f050e2d @rosejn adding more docs
rosejn authored
56 ; start a server and create a client to talk with it
d1b92a0 @samaaron update readme
samaaron authored
57 (def server (osc-server PORT))
f050e2d @rosejn adding more docs
rosejn authored
58 (def client (osc-client "localhost" PORT))
d1b92a0 @samaaron update readme
samaaron authored
59
f050e2d @rosejn adding more docs
rosejn authored
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}
d1b92a0 @samaaron update readme
samaaron authored
63 (osc-handle server "/test" (fn [msg] (println "MSG: " (:args msg))) :my-handler)
64
f050e2d @rosejn adding more docs
rosejn authored
65 ; send it some messages
66 (doseq [val (range 10)]
67 (osc-send client "/test" "i" val))
d1b92a0 @samaaron update readme
samaaron authored
68
f050e2d @rosejn adding more docs
rosejn authored
69 (Thread/sleep 1000)
d1b92a0 @samaaron update readme
samaaron authored
70
71 ;remove handler
72 (osc-rm-handler server "/test" :my-handler)
73
f050e2d @rosejn adding more docs
rosejn authored
74 ; stop listening and deallocate resources
75 (osc-close client)
76 (osc-close server)
77
c090837 @samaaron update README
samaaron authored
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:
f050e2d @rosejn adding more docs
rosejn authored
166
167 (in-osc-bundle client (+ (osc-now) 1000)
c090837 @samaaron update README
samaaron authored
168 (osc-send client "/foo" "bar" 42)
d1b92a0 @samaaron update readme
samaaron authored
169
f050e2d @rosejn adding more docs
rosejn authored
170 ; Call functions that send more osc messages
171 (do-stuff client))
172
c090837 @samaaron update README
samaaron authored
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.
d1b92a0 @samaaron update readme
samaaron authored
181
c090837 @samaaron update README
samaaron authored
182 The basic matchers are:
d1b92a0 @samaaron update readme
samaaron authored
183
c2799c1 @samaaron minor readme fixes
samaaron authored
184 * `*` Matches 0 or more arbitrary chars (`osc-clj` implements this in a non-greedy way)
c090837 @samaaron update README
samaaron authored
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
f050e2d @rosejn adding more docs
rosejn authored
190
c090837 @samaaron update README
samaaron authored
191
192 The matchers may also be combined:
193
c2799c1 @samaaron minor readme fixes
samaaron authored
194 /foo/{bar,baz}/*/*quux?/[abc]def[!h]/phasor[0-9]/
c090837 @samaaron update README
samaaron authored
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
c2799c1 @samaaron minor readme fixes
samaaron authored
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:
c090837 @samaaron update README
samaaron authored
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:
d596dc0 @rosejn Initial creation of osc submodule.
rosejn authored
217
3f9f05d @rosejn changing to Overtone project namespace
rosejn authored
218 Include in your project.clj like so:
219
c2799c1 @samaaron minor readme fixes
samaaron authored
220 [overtone/osc-clj "0.4.1"]
3f9f05d @rosejn changing to Overtone project namespace
rosejn authored
221
c090837 @samaaron update README
samaaron authored
222 ### Source Repository
d596dc0 @rosejn Initial creation of osc submodule.
rosejn authored
223 Downloads and the source repository can be found on GitHub:
224
d1b92a0 @samaaron update readme
samaaron authored
225 http://github.com/overtone/osc-clj
d596dc0 @rosejn Initial creation of osc submodule.
rosejn authored
226
d1b92a0 @samaaron update readme
samaaron authored
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:
d596dc0 @rosejn Initial creation of osc submodule.
rosejn authored
229
d1b92a0 @samaaron update readme
samaaron authored
230 http://github.com/overtone/overtone
d596dc0 @rosejn Initial creation of osc submodule.
rosejn authored
231
f050e2d @rosejn adding more docs
rosejn authored
232
c090837 @samaaron update README
samaaron authored
233 ### Mailing List
d596dc0 @rosejn Initial creation of osc submodule.
rosejn authored
234
c090837 @samaaron update README
samaaron authored
235 For any questions, comments or patches, use the Overtone google group:
d596dc0 @rosejn Initial creation of osc submodule.
rosejn authored
236
237 http://groups.google.com/group/overtone
238
c090837 @samaaron update README
samaaron authored
239 ## Authors
d596dc0 @rosejn Initial creation of osc submodule.
rosejn authored
240
241 * Jeff Rose
c090837 @samaaron update README
samaaron authored
242 * Sam Aaron
99f1038 @rosejn adding mw10013 to contributors
rosejn authored
243
244 ### Contributors
245 * mw10013
Something went wrong with that request. Please try again.