annotate README_OSC.md @ 2539:98321b83ac9b

Add any persistent config defines (e.g. feedback request)
author Chris Cannam
date Thu, 14 May 2020 19:03:05 +0100
parents 2179bf9757a0
children
rev   line source
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