Chris@404
|
1
|
Chris@404
|
2 OSC control of Sonic Visualiser
|
Chris@404
|
3 ===============================
|
Chris@404
|
4
|
Chris@404
|
5 Sonic Visualiser can be controlled remotely using the Open Sound
|
Chris@2521
|
6 Control protocol. This facility requires the
|
Chris@2521
|
7 [liblo](http://liblo.sourceforge.net/) (Lite OSC) library by Steve
|
Chris@2521
|
8 Harris and Stephen Sinclair to have been available when Sonic
|
Chris@2521
|
9 Visualiser was built.
|
Chris@404
|
10
|
Chris@2520
|
11 Sonic Visualiser opens a single OSC port on startup, provided that OSC
|
Chris@2520
|
12 support is compiled in, the `--no-osc` command-line option has not
|
Chris@2520
|
13 been supplied, and permission to use the network was not refused by
|
Chris@2520
|
14 the user the first time Sonic Visualiser was run.
|
Chris@2520
|
15
|
Chris@2520
|
16 The URL of the OSC port is printed to standard output on startup, or
|
Chris@2520
|
17 can be read from the About box on the Help menu.
|
Chris@2520
|
18
|
Chris@2520
|
19
|
Chris@2520
|
20 General outline
|
Chris@2520
|
21 ---------------
|
Chris@404
|
22
|
Chris@404
|
23 OSC commands accepted by Sonic Visualiser take the form:
|
Chris@404
|
24
|
Chris@2520
|
25 ```
|
Chris@2520
|
26 <scheme>://<host>:<port>/<method> [<arg> ...]
|
Chris@2520
|
27 ```
|
Chris@404
|
28
|
Chris@2520
|
29 For example, `osc.udp://localhost:12654/play 2.0` will play the
|
Chris@404
|
30 current session from time 2.0 seconds.
|
Chris@404
|
31
|
Chris@404
|
32 Methods that manipulate panes or layers act on the currently selected
|
Chris@2520
|
33 pane or layer. Use the `setcurrent` method to choose the right target
|
Chris@404
|
34 for subsequent such methods.
|
Chris@404
|
35
|
Chris@2520
|
36
|
Chris@2520
|
37 OSC clients and invocation
|
Chris@2520
|
38 --------------------------
|
Chris@2520
|
39
|
Chris@495
|
40 If you need an OSC client, there is a small program in the svcore
|
Chris@2520
|
41 library at `svcore/data/osc/sv-osc-send.c` that sends an OSC method
|
Chris@2520
|
42 and arguments to a given URL -- this is not specific to SV but will
|
Chris@2520
|
43 work with it. To compile that program you should only have to run
|
Chris@495
|
44
|
Chris@2520
|
45 ```
|
Chris@2520
|
46 $ gcc sv-osc-send.c -o sv-osc-send -llo
|
Chris@2520
|
47 ```
|
Chris@495
|
48
|
Chris@495
|
49 provided you have liblo installed.
|
Chris@495
|
50
|
Chris@495
|
51 Then there is a small shell script in the same directory, called
|
Chris@2520
|
52 `sv-command`, that provides a basic command shell for Sonic
|
Chris@2520
|
53 Visualiser. Start SV first, then `sv-command` should find its OSC
|
Chris@2520
|
54 port from the system process table when you start it. For example:
|
Chris@495
|
55
|
Chris@2520
|
56 ```
|
Chris@2520
|
57 $ PATH=.:$PATH ./sv-command # Set PATH so it can find sv-osc-send
|
Chris@2520
|
58 /open snare_hex.wav
|
Chris@2520
|
59 /add spectrogram
|
Chris@2520
|
60 /set layer Colour Sunset
|
Chris@2520
|
61 /play
|
Chris@2520
|
62 /quit
|
Chris@2520
|
63 $
|
Chris@2520
|
64 ```
|
Chris@404
|
65
|
Chris@2520
|
66 You can also start Sonic Visualiser directly in "OSC script" mode by
|
Chris@2520
|
67 supplying the `--osc-script <filename>` command-line option. The
|
Chris@2520
|
68 argument to this should be the path of a text file containing a series
|
Chris@2520
|
69 of OSC commands (like those in the example above). These will be
|
Chris@2520
|
70 executed in succession as quickly as possible. A line that contains
|
Chris@2520
|
71 only a number, instead of a command, will cause SV to pause for that
|
Chris@2520
|
72 number of seconds before going on with the script. Lines beginning
|
Chris@2520
|
73 with `#` are ignored.
|
Chris@404
|
74
|
Chris@2520
|
75 If you supply "-" as the filename argument to the `--osc-script`
|
Chris@2520
|
76 option, SV will instead read OSC commands from standard input. So you
|
Chris@2520
|
77 can do something like
|
Chris@404
|
78
|
Chris@2520
|
79 ```
|
Chris@2520
|
80 $ rlwrap sonic-visualiser --osc-script - /path/to/filename.wav
|
Chris@2520
|
81 ```
|
Chris@404
|
82
|
Chris@2520
|
83 to obtain a rather limited Sonic Visualiser OSC read-eval loop.
|
Chris@404
|
84
|
Chris@404
|
85
|
Chris@2520
|
86 Method reference
|
Chris@2520
|
87 ----------------
|
Chris@404
|
88
|
Chris@2520
|
89 ### File management
|
Chris@404
|
90
|
Chris@2520
|
91 ```
|
Chris@2520
|
92 /open <filename>
|
Chris@2520
|
93 ```
|
Chris@404
|
94
|
Chris@2520
|
95 Open a new file (of type determined by Sonic Visualiser). If it is an
|
Chris@2520
|
96 audio file, use it to replace the existing main audio file (if any).
|
Chris@404
|
97
|
Chris@2520
|
98 ```
|
Chris@2520
|
99 /openadditional <filename>
|
Chris@2520
|
100 ```
|
Chris@404
|
101
|
Chris@2520
|
102 Open a new file. If it is an audio file, open it in a new pane in
|
Chris@2520
|
103 addition to the existing audio file (if any).
|
Chris@404
|
104
|
Chris@2520
|
105 ```
|
Chris@2520
|
106 /recent <n>
|
Chris@2520
|
107 /last
|
Chris@2520
|
108 ```
|
Chris@404
|
109
|
Chris@2520
|
110 Open the `<n>`th most recent file from the Recent Files menu, counting
|
Chris@2520
|
111 from 1 for the most recent file opened. "last" is a synonym for
|
Chris@2520
|
112 "recent 1".
|
Chris@404
|
113
|
Chris@2520
|
114 ```
|
Chris@2520
|
115 /save <filename>
|
Chris@2520
|
116 ```
|
Chris@2242
|
117
|
Chris@2520
|
118 Save the current session in `<filename>` as an SV session file.
|
Chris@2242
|
119
|
Chris@2520
|
120 This action will try to fail rather than overwrite an existing file,
|
Chris@2520
|
121 but you probably shouldn't rely on that.
|
Chris@404
|
122
|
Chris@2520
|
123 ```
|
Chris@2520
|
124 /export <filename>
|
Chris@2520
|
125 ```
|
Chris@404
|
126
|
Chris@2520
|
127 Export the main audio file to `<filename>` in floating-point extended
|
Chris@2520
|
128 WAV format. If a region is selected, export only that region.
|
Chris@404
|
129
|
Chris@2520
|
130 This action will try to fail rather than overwrite an existing
|
Chris@2520
|
131 file, but you probably shouldn't rely on that.
|
Chris@404
|
132
|
Chris@2520
|
133 ```
|
Chris@2520
|
134 /exportlayer <filename>
|
Chris@2520
|
135 ```
|
Chris@404
|
136
|
Chris@2520
|
137 Export the current layer to `<filename>`. See `/setcurrent` for how to
|
Chris@2520
|
138 change which layer is current. The format to use is determined from
|
Chris@2520
|
139 the file extension of `<filename>`:
|
Chris@404
|
140
|
Chris@2520
|
141 * `xml`, `svl` - Sonic Visualiser layer file formats
|
Chris@2520
|
142 * `mid`, `midi` - MIDI (note layers only)
|
Chris@2520
|
143 * `ttl`, `n3` - Audio Features Ontology RDF/Turtle (only some layer types)
|
Chris@2520
|
144 * `csv` - Comma-separated text
|
Chris@2520
|
145 * anything else - Tab-separated text
|
Chris@404
|
146
|
Chris@2520
|
147 If a region is currently selected, and the file type is CSV,
|
Chris@2520
|
148 tab-separated, or MIDI, export only that region. Otherwise export
|
Chris@2520
|
149 the whole layer.
|
Chris@404
|
150
|
Chris@2520
|
151 This action will try to fail rather than overwrite an existing
|
Chris@2520
|
152 file, but you probably shouldn't rely on that.
|
Chris@404
|
153
|
Chris@2520
|
154 ```
|
Chris@2520
|
155 /exportimage <filename>
|
Chris@2520
|
156 ```
|
Chris@404
|
157
|
Chris@2520
|
158 Export a PNG image of the contents of the current pane to
|
Chris@2520
|
159 `<filename>`. See `/setcurrent` for how to change which pane is
|
Chris@2520
|
160 current. If a region is currently selected, export only that
|
Chris@2520
|
161 region. Otherwise export the whole pane. Currently the export will
|
Chris@2520
|
162 fail if the area to be exported is more than 32767 pixels wide.
|
Chris@404
|
163
|
Chris@2520
|
164 To export to an image of a fixed width regardless of model duration,
|
Chris@2520
|
165 consider using `/zoom fit` to zoom the model contents to fit the
|
Chris@2520
|
166 window width, then optionally zooming in or out a known number of
|
Chris@2520
|
167 steps, before exporting.
|
Chris@404
|
168
|
Chris@2520
|
169 This action will try to fail rather than overwrite an existing file,
|
Chris@2520
|
170 but you probably shouldn't rely on that.
|
Chris@404
|
171
|
Chris@2520
|
172 ```
|
Chris@2520
|
173 /exportsvg <filename>
|
Chris@2520
|
174 ```
|
Chris@404
|
175
|
Chris@2520
|
176 Export a SVG vector graphic of the contents of the current pane to
|
Chris@2520
|
177 `<filename>`. See `/setcurrent` for how to change which pane is
|
Chris@2520
|
178 current. If a region is currently selected, export only that
|
Chris@2520
|
179 region. Otherwise export the whole pane.
|
Chris@404
|
180
|
Chris@2520
|
181 This action will try to fail rather than overwrite an existing file,
|
Chris@2520
|
182 but you probably shouldn't rely on that.
|
Chris@404
|
183
|
Chris@404
|
184
|
Chris@2520
|
185 ### Playback control
|
Chris@404
|
186
|
Chris@2520
|
187 ```
|
Chris@2520
|
188 /jump <t>
|
Chris@2520
|
189 /jump end
|
Chris@2520
|
190 /jump selection
|
Chris@2520
|
191 ```
|
Chris@404
|
192
|
Chris@2520
|
193 Jump the playback position to time `<t>` (in seconds); or to the end
|
Chris@2520
|
194 of the file; or to the start of the current selection.
|
Chris@404
|
195
|
Chris@2520
|
196 ```
|
Chris@2520
|
197 /play
|
Chris@2520
|
198 /play <t>
|
Chris@2520
|
199 /play selection
|
Chris@2520
|
200 ```
|
Chris@404
|
201
|
Chris@2520
|
202 Start playback. If a time `<t>` is given, start from that time in
|
Chris@2520
|
203 seconds. If the word `selection` is given instead, play the current
|
Chris@2520
|
204 selection.
|
Chris@404
|
205
|
Chris@2520
|
206 ```
|
Chris@2520
|
207 /stop
|
Chris@2520
|
208 ```
|
Chris@404
|
209
|
Chris@2520
|
210 Stop playback.
|
Chris@404
|
211
|
Chris@2520
|
212 ```
|
Chris@2520
|
213 /loop on
|
Chris@2520
|
214 /loop off
|
Chris@2520
|
215 ```
|
Chris@404
|
216
|
Chris@2520
|
217 Switch playback loop mode on or off.
|
Chris@404
|
218
|
Chris@404
|
219
|
Chris@2520
|
220 ### Panes, layers, and the window
|
Chris@404
|
221
|
Chris@2520
|
222 ```
|
Chris@2520
|
223 /add <layertype>
|
Chris@2520
|
224 /add <layertype> <channel>
|
Chris@2520
|
225 ```
|
Chris@404
|
226
|
Chris@2520
|
227 Add a new pane containing a layer of the given type, based on the
|
Chris@2520
|
228 given channel of the main audio file (numbered from 0). If no
|
Chris@2525
|
229 `<channel>` is specified, mix all channels. The specified layer is
|
Chris@2525
|
230 made the current layer, and the new pane becomes the current pane.
|
Chris@404
|
231
|
Chris@2520
|
232 Useful values of `<layertype>` are:
|
Chris@404
|
233
|
Chris@2520
|
234 ```
|
Chris@2520
|
235 waveform
|
Chris@2520
|
236 spectrogram
|
Chris@2520
|
237 melodicrange
|
Chris@2520
|
238 peakfrequency
|
Chris@2520
|
239 spectrum
|
Chris@2520
|
240 timeruler
|
Chris@2520
|
241 ```
|
Chris@404
|
242
|
Chris@2520
|
243 The following `<layertype>`s are also accepted:
|
Chris@404
|
244
|
Chris@2520
|
245 ```
|
Chris@2520
|
246 timeinstants
|
Chris@2520
|
247 timevalues
|
Chris@2520
|
248 notes
|
Chris@2520
|
249 text
|
Chris@2520
|
250 colour3dplot
|
Chris@2520
|
251 ```
|
Chris@404
|
252
|
Chris@2520
|
253 But they are less useful, as they create empty layers which there is
|
Chris@2520
|
254 currently no OSC support for editing.
|
Chris@404
|
255
|
Chris@2520
|
256 ```
|
Chris@2520
|
257 /setcurrent <pane>
|
Chris@2520
|
258 /setcurrent <pane> <layer>
|
Chris@2520
|
259 ```
|
Chris@404
|
260
|
Chris@2520
|
261 Make the given `<pane>` (a number counting from 1 for the topmost
|
Chris@2520
|
262 pane) and optionally the given `<layer>` on that pane (a number
|
Chris@2520
|
263 counting from 1 for the "frontmost" layer) the current pane and layer
|
Chris@2520
|
264 for subsequent pane and layer operations.
|
Chris@404
|
265
|
Chris@2520
|
266 ```
|
Chris@2520
|
267 /delete pane
|
Chris@2520
|
268 /delete layer
|
Chris@2520
|
269 ```
|
Chris@404
|
270
|
Chris@2520
|
271 Delete the current pane or layer.
|
Chris@404
|
272
|
Chris@2520
|
273 ```
|
Chris@2520
|
274 /set <control> <value>
|
Chris@2520
|
275 /set pane <control> <value>
|
Chris@2520
|
276 /set layer <control> <value>
|
Chris@2520
|
277 ```
|
Chris@404
|
278
|
Chris@2520
|
279 Set a main window control; a property of the current pane; or a
|
Chris@2520
|
280 property of the current layer.
|
Chris@404
|
281
|
Chris@2520
|
282 Accepted main window controls are:
|
Chris@404
|
283
|
Chris@2520
|
284 * `gain` - whose values are linear multipliers (i.e. 1.0 == unity gain).
|
Chris@2520
|
285 * `speed` - takes a value of a percentage change in playback speed,
|
Chris@2520
|
286 so 100 is the default playback speed, 200 sets double the default
|
Chris@2520
|
287 speed, and 50 sets half the default.
|
Chris@2520
|
288 * `overlays` - controls the verbosity level of the text overlays on
|
Chris@2520
|
289 each pane, from 0 (everything off) to 2 (everything on).
|
Chris@2520
|
290 * `zoomwheels` - controls whether the zoom wheels are displayed (1)
|
Chris@2520
|
291 or not (0).
|
Chris@2520
|
292 * `propertyboxes` - controls whether the property boxes are displayed
|
Chris@2520
|
293 (1) or not (0).
|
Chris@404
|
294
|
Chris@2520
|
295 For pane and layer properties, the control name is the displayed name
|
Chris@2520
|
296 of the given property (though you may use "-" or "_" in place of any
|
Chris@2520
|
297 spaces in the name if it's easier for you). The value may be the
|
Chris@2520
|
298 displayed value or underlying integer for the property.
|
Chris@404
|
299
|
Chris@2520
|
300 Some examples:
|
Chris@2520
|
301
|
Chris@2520
|
302 ```
|
Chris@2520
|
303 /set pane Global-Scroll off
|
Chris@2520
|
304 /set pane Follow_Playback Scroll
|
Chris@2520
|
305 /set layer Colour Blue
|
Chris@2520
|
306 /set layer Scale-Units dB
|
Chris@2520
|
307 /set layer Frequency-Scale Log
|
Chris@2520
|
308 ```
|
Chris@2520
|
309
|
Chris@2520
|
310 Note that while you can use "-" or "_" in place of spaces in the
|
Chris@2520
|
311 property name, you cannot currently do so in the value text. If
|
Chris@2520
|
312 this is a problem for you, you might be able to set the value
|
Chris@2520
|
313 as an integer instead (all layer properties can be set this way).
|
Chris@2520
|
314
|
Chris@2520
|
315 ```
|
Chris@2520
|
316 /zoom <level>
|
Chris@2520
|
317 /zoom in
|
Chris@2520
|
318 /zoom out
|
Chris@2520
|
319 /zoom fit
|
Chris@2520
|
320 /zoom default
|
Chris@2520
|
321 ```
|
Chris@2520
|
322
|
Chris@2520
|
323 Zoom to a given zoom `<level>`, given in audio sample frames per
|
Chris@2520
|
324 pixel; or zoom in or out one step from the current level; or zoom so
|
Chris@2520
|
325 that the whole model duration fits in the current view width; or
|
Chris@2520
|
326 return to the default zoom level. This method acts on the current
|
Chris@2520
|
327 pane (it only affects all panes if set to Global Zoom, which is the
|
Chris@2520
|
328 default).
|
Chris@2520
|
329
|
Chris@2520
|
330 ```
|
Chris@2520
|
331 /zoomvertical <min> <max>
|
Chris@2520
|
332 /zoomvertical in
|
Chris@2520
|
333 /zoomvertical out
|
Chris@2520
|
334 /zoomvertical default
|
Chris@2520
|
335 ```
|
Chris@2520
|
336
|
Chris@2520
|
337 Change the vertical zoom and origin so as to show the value range from
|
Chris@2520
|
338 `<min>` to `<max>` in the vertical scale; or zoom in or out
|
Chris@2520
|
339 vertically; or return to the default vertical zoom level. The effect
|
Chris@2520
|
340 of this method is heavily dependent on the current layer.
|
Chris@2520
|
341
|
Chris@2520
|
342 ```
|
Chris@2525
|
343 /resize <w> <h>
|
Chris@2525
|
344 ```
|
Chris@2525
|
345
|
Chris@2525
|
346 Resize the main window to width `<w>` and height `<h>` (if the window
|
Chris@2525
|
347 system permits).
|
Chris@2525
|
348
|
Chris@2525
|
349
|
Chris@2525
|
350 ### Region selection
|
Chris@2525
|
351
|
Chris@2525
|
352 ```
|
Chris@2525
|
353 /select <t0> <t1>
|
Chris@2525
|
354 /select all
|
Chris@2525
|
355 /select none
|
Chris@2525
|
356 ```
|
Chris@2525
|
357
|
Chris@2525
|
358 Select the region from times `<t0>` to `<t1>` in seconds; or select
|
Chris@2525
|
359 the whole file; or clear the selection. If there is a layer selected
|
Chris@2525
|
360 that can be used as a snap guide for the selection, then the selection
|
Chris@2525
|
361 will be snapped to it (in the same manner as when making selections
|
Chris@2525
|
362 interactively).
|
Chris@2525
|
363
|
Chris@2525
|
364 ```
|
Chris@2525
|
365 /addselect <t0> <t1>
|
Chris@2525
|
366 ```
|
Chris@2525
|
367
|
Chris@2525
|
368 Make an additional selection (leaving any existing selection in place)
|
Chris@2525
|
369 from times `<t0>` to `<t1>` in seconds.
|
Chris@2525
|
370
|
Chris@2525
|
371
|
Chris@2525
|
372 ### Feature extraction
|
Chris@2525
|
373
|
Chris@2525
|
374 ```
|
Chris@2520
|
375 /transform <name>
|
Chris@2520
|
376 ```
|
Chris@2520
|
377
|
Chris@2520
|
378 Transform the current main audio file using the named transform.
|
Chris@2520
|
379 Transforms are named according to the scheme
|
Chris@2520
|
380
|
Chris@2520
|
381 ```
|
Chris@2520
|
382 type:source:plugin:output
|
Chris@2520
|
383 ```
|
Chris@2520
|
384
|
Chris@2520
|
385 For example, the percussion onset detector from the Vamp example
|
Chris@2520
|
386 plugin set can be invoked via
|
Chris@2520
|
387
|
Chris@2520
|
388 ```
|
Chris@2520
|
389 /transform vamp:vamp-example-plugins:percussiononsets:onsets
|
Chris@2520
|
390 ```
|
Chris@2520
|
391
|
Chris@2520
|
392 If the output is omitted, the first is used. Note that you need to
|
Chris@2520
|
393 use the plugin and output name, not description: in this case
|
Chris@2520
|
394 `percussiononsets` rather than "Simple Percussion Onset Detector".
|
Chris@2520
|
395
|
Chris@2520
|
396 There is not yet any way to run a transform via OSC on any but the
|
Chris@2520
|
397 main audio file, nor with any but its default parameters, processing
|
Chris@2520
|
398 block/step size, or channel selection.
|
Chris@2520
|
399
|
Chris@2520
|
400
|
Chris@2520
|
401 ### Housekeeping
|
Chris@2520
|
402
|
Chris@2520
|
403 ```
|
Chris@2520
|
404 /undo
|
Chris@2520
|
405 /redo
|
Chris@2520
|
406 ```
|
Chris@2520
|
407
|
Chris@2520
|
408 Undo the last editing operation; redo the last undone operation. Note
|
Chris@2520
|
409 that most of the classic editing operations (copy and paste etc) are
|
Chris@2520
|
410 not controllable via OSC, but undo may still be useful because Sonic
|
Chris@2520
|
411 Visualiser considers actions such as adding a pane to be undoable
|
Chris@2520
|
412 editing operations as well.
|
Chris@2520
|
413
|
Chris@2520
|
414 ```
|
Chris@2520
|
415 /quit
|
Chris@2520
|
416 ```
|
Chris@2520
|
417
|
Chris@2520
|
418 Exit the program abruptly without saving.
|
Chris@2520
|
419
|
Chris@2520
|
420
|
Chris@2520
|
421 ### Missing things
|
Chris@2520
|
422
|
Chris@2520
|
423 Handy features still missing from the OSC interface include:
|
Chris@404
|
424
|
Chris@404
|
425 * the ability to run transforms with non-default parameters or
|
Chris@404
|
426 starting from different source models
|
Chris@404
|
427 * the ability to add layers to a pane (without transform)
|
Chris@404
|
428 * the ability to add panes (and layers) showing any but the
|
Chris@404
|
429 main model
|
Chris@404
|
430 * the ability to set play parameters on a layer/model and show/hide it
|
Chris@2520
|
431 * the ability to import layers
|
Chris@404
|
432 * a working pane resize
|
Chris@404
|
433 * the ability to rename a layer
|
Chris@404
|
434
|
Chris@404
|
435
|