annotate README.OSC @ 2344:9690acc4cca3

Fix #1931 Top of property box is snipped off on Mac
author Chris Cannam
date Mon, 07 Oct 2019 14:30:44 +0100
parents e9c77a4c865e
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@404 6 Control protocol. This facility requires Steve Harris's liblo (Lite
Chris@404 7 OSC) library to have been available when Sonic Visualiser was built.
Chris@404 8
Chris@404 9 Sonic Visualiser opens a single OSC port on startup. The URL of this
Chris@404 10 port is printed to standard output on startup, or can be read from the
Chris@404 11 About box on the Help menu.
Chris@404 12
Chris@404 13 OSC commands accepted by Sonic Visualiser take the form:
Chris@404 14
Chris@404 15 <scheme>://<host>:<port>/<method> [<arg> ...]
Chris@404 16
Chris@404 17 For example, "osc.udp://localhost:12654/play 2.0" will play the
Chris@404 18 current session from time 2.0 seconds.
Chris@404 19
Chris@404 20 Methods that manipulate panes or layers act on the currently selected
Chris@404 21 pane or layer. Use the setcurrent method to choose the right target
Chris@404 22 for subsequent such methods.
Chris@404 23
Chris@495 24 If you need an OSC client, there is a small program in the svcore
Chris@495 25 library at
Chris@495 26
Chris@495 27 svcore/data/osc/sv-osc-send.c
Chris@495 28
Chris@495 29 that sends an OSC method and arguments to a given URL -- this is not
Chris@495 30 specific to SV but will work with it. To compile that program you
Chris@495 31 should only have to run
Chris@495 32
Chris@495 33 $ gcc sv-osc-send.c -o sv-osc-send -llo
Chris@495 34
Chris@495 35 provided you have liblo installed.
Chris@495 36
Chris@495 37 Then there is a small shell script in the same directory, called
Chris@495 38 sv-command, that provides a basic command shell for Sonic Visualiser.
Chris@495 39 Start SV first, then sv-command should find its OSC port from the
Chris@495 40 system process table when you start it.
Chris@495 41 For example:
Chris@495 42
Chris@495 43 $ PATH=.:$PATH ./sv-command # Set PATH so it can find sv-osc-send
Chris@495 44 /open snare_hex.wav
Chris@495 45 /add spectrogram
Chris@495 46 /set layer Colour Sunset
Chris@495 47 /play
Chris@495 48 /quit
Chris@495 49 $
Chris@404 50
Chris@404 51
Chris@404 52 OSC methods available
Chris@404 53 =====================
Chris@404 54
Chris@404 55 Main window methods
Chris@404 56 -------------------
Chris@404 57
Chris@404 58 /open <filename>
Chris@404 59
Chris@404 60 Open a new file (of type determined by Sonic Visualiser).
Chris@404 61 If it is an audio file, use it to replace the existing main
Chris@404 62 audio file (if any).
Chris@404 63
Chris@404 64 /openadditional <filename>
Chris@404 65
Chris@404 66 Open a new file. If it is an audio file, open it in a new
Chris@404 67 pane in addition to the existing audio file (if any).
Chris@404 68
Chris@404 69 /recent <n>
Chris@404 70 /last
Chris@404 71
Chris@404 72 Open the <n>'th most recent file from the Recent Files menu,
Chris@404 73 counting from 1 for the most recent file opened. "last" is a
Chris@404 74 synonym for "recent 1".
Chris@404 75
Chris@404 76 /save <filename>
Chris@404 77
Chris@404 78 Save the current session in <filename> as an SV session file.
Chris@404 79 This action will try to fail rather than overwrite an existing
Chris@404 80 file, but you probably shouldn't rely on that.
Chris@404 81
Chris@404 82 /export <filename>
Chris@404 83
Chris@404 84 Export the (first) selected area of the main audio file
Chris@404 85 (or all of it, if there is no selection) in <filename>, as a
Chris@404 86 WAV file. This action will try to fail rather than overwrite
Chris@404 87 an existing file, but you probably shouldn't rely on that.
Chris@404 88
Chris@2242 89 /exportlayer <filename>
Chris@2242 90
Chris@2242 91 Export the current layer to a file, of type determined from the
Chris@2242 92 file's suffix. See /setcurrent for how to change which layer is
Chris@2242 93 current. This action will try to fail rather than overwrite an
Chris@2242 94 existing file, but you probably shouldn't rely on that.
Chris@2242 95
Chris@404 96 /jump <t>
Chris@404 97 /jump end
Chris@404 98 /jump selection
Chris@404 99
Chris@404 100 Jump the playback position to time <t> (in seconds); or to
Chris@404 101 the end of the file; or to the start of the current selection.
Chris@404 102
Chris@404 103 /play
Chris@404 104 /play <t>
Chris@404 105 /play selection
Chris@404 106
Chris@404 107 Start playback. If a time <t> is given, start from that time
Chris@404 108 in seconds. If the word "selection" is given instead, play
Chris@404 109 the current selection.
Chris@404 110
Chris@404 111 /stop
Chris@404 112
Chris@404 113 Stop playback.
Chris@404 114
Chris@404 115 /loop on
Chris@404 116 /loop off
Chris@404 117
Chris@404 118 Switch playback loop mode on or off.
Chris@404 119
Chris@404 120 /select <t0> <t1>
Chris@404 121 /select all
Chris@404 122 /select none
Chris@404 123
Chris@404 124 Select the region from times <t0> to <t1> in seconds; or select
Chris@404 125 the whole file; or clear the selection. If there is a layer
Chris@404 126 selected that can be used as a snap guide for the selection, then
Chris@404 127 the selection will be snapped to it (in the same manner as when
Chris@404 128 making selections interactively).
Chris@404 129
Chris@404 130 /addselect <t0> <t1>
Chris@404 131
Chris@404 132 Make an additional selection (leaving any existing selection
Chris@404 133 in place) from times <t0> to <t1> in seconds.
Chris@404 134
Chris@404 135 /undo
Chris@404 136 /redo
Chris@404 137
Chris@404 138 Undo the last editing operation; redo the last undone operation.
Chris@404 139 Note that most of the classic editing operations (copy and paste
Chris@404 140 etc) are not controllable via OSC, but undo may still be useful
Chris@404 141 because Sonic Visualiser considers actions such as adding a pane
Chris@404 142 to be undoable editing operations as well.
Chris@404 143
Chris@404 144 /add <layertype>
Chris@404 145 /add <layertype> <channel>
Chris@404 146
Chris@404 147 Add a new pane containing a layer of the given type, based on
Chris@404 148 the main audio file. If no <channel> is specified, use all
Chris@404 149 available channels. Useful <layertype>s are:
Chris@404 150
Chris@404 151 waveform
Chris@404 152 spectrogram
Chris@404 153 spectrum
Chris@404 154 timeruler
Chris@404 155
Chris@404 156 The following <layertype>s are less useful, because they create
Chris@404 157 empty layers which there is currently no OSC support for editing:
Chris@404 158
Chris@404 159 timeinstants
Chris@404 160 timevalues
Chris@404 161 notes
Chris@404 162 text
Chris@404 163 colour3dplot
Chris@404 164
Chris@404 165 /set <control> <value>
Chris@404 166 /set pane <control> <value>
Chris@404 167 /set layer <control> <value>
Chris@404 168
Chris@404 169 Set a main window control; a property of the current pane; or a
Chris@404 170 property of the current layer.
Chris@404 171
Chris@404 172 Accepted main window <control>s are:
Chris@404 173
Chris@404 174 gain
Chris@404 175 whose values are linear multipliers (i.e. 1.0 == unity gain).
Chris@404 176
Chris@1617 177 speed
Chris@1617 178 takes a value of a percentage change in playback
Chris@1617 179 speed, so 100 is the default playback speed, 200 sets
Chris@1617 180 double the default speed, and 50 sets half the default.
Chris@404 181
Chris@404 182 overlays
Chris@404 183 controls the verbosity level of the text overlays on
Chris@404 184 each pane, from 0 (everything off) to 2 (everything on).
Chris@404 185
Chris@404 186 zoomwheels
Chris@404 187 controls whether the zoom wheels are displayed (1) or not (0).
Chris@404 188
Chris@404 189 propertyboxes
Chris@404 190 controls whether the property boxes are displayed (1) or not (0).
Chris@404 191
Chris@404 192 For pane and layer properties, the control name is the displayed
Chris@404 193 name of the given property (though you may use "-" or "_" in place
Chris@404 194 of any spaces in the name if it's easier for you). The value may
Chris@404 195 be the displayed value or underlying integer for the property.
Chris@404 196
Chris@404 197 Some examples:
Chris@404 198
Chris@404 199 /set pane Global-Scroll off
Chris@404 200 /set pane Follow_Playback Scroll
Chris@404 201 /set layer Colour Blue
Chris@404 202 /set layer Scale-Units dB
Chris@404 203 /set layer Frequency-Scale Log
Chris@404 204
Chris@404 205 Note that while you can use "-" or "_" in place of spaces in the
Chris@404 206 property name, you cannot currently do so in the value text. If
Chris@404 207 this is a problem for you, you might be able to set the value
Chris@404 208 as an integer instead (all layer properties can be set this way).
Chris@404 209
Chris@404 210 /setcurrent <pane>
Chris@404 211 /setcurrent <pane> <layer>
Chris@404 212
Chris@404 213 Make the given <pane> (a number counting from 1 for the topmost
Chris@404 214 pane) and optionally the given <layer> on that pane (a number
Chris@404 215 counting from 1 for the "frontmost" layer) the current pane and
Chris@404 216 layer for subsequent pane and layer operations.
Chris@404 217
Chris@404 218 /delete pane
Chris@404 219 /delete layer
Chris@404 220
Chris@404 221 Delete the current pane or layer.
Chris@404 222
Chris@404 223 /zoom <level>
Chris@404 224 /zoom in
Chris@404 225 /zoom out
Chris@404 226 /zoom default
Chris@404 227
Chris@404 228 Zoom to a given zoom <level>, given in audio sample frames per
Chris@404 229 pixel; or zoom in or out one step from the current level; or
Chris@404 230 return to the default zoom level. This method acts on the
Chris@404 231 current pane (it only affects all panes if set to Global Zoom,
Chris@404 232 which is the default).
Chris@404 233
Chris@404 234 /zoomvertical <min> <max>
Chris@404 235 /zoomvertical in
Chris@404 236 /zoomvertical out
Chris@404 237 /zoomvertical default
Chris@404 238
Chris@404 239 Change the vertical zoom and origin so as to show the value
Chris@404 240 range from <min> to <max> in the vertical scale; or zoom in or
Chris@404 241 out vertically; or return to the default vertical zoom level.
Chris@404 242 The effect of this method is heavily dependent on the current
Chris@404 243 layer.
Chris@404 244
Chris@404 245 /transform <name>
Chris@404 246
Chris@404 247 Transform the current main audio file using the named transform.
Chris@404 248 Transforms are named according to the scheme
Chris@404 249
Chris@404 250 type:source:plugin:output
Chris@404 251
Chris@404 252 For example, the percussion onset detector from the Vamp example
Chris@404 253 plugin set can be invoked via
Chris@404 254
Chris@404 255 /transform vamp:vamp-example-plugins:percussiononsets:onsets
Chris@404 256
Chris@404 257 If the output is omitted, the first is used. Note that you
Chris@404 258 need to use the plugin and output name, not description: in
Chris@404 259 this case "percussiononsets" rather than "Simple Percussion
Chris@404 260 Onset Detector".
Chris@404 261
Chris@404 262 There is not yet any way to run a transform via OSC on any but
Chris@404 263 the main audio file, nor with any but its default parameters,
Chris@404 264 processing block/step size, or channel selection.
Chris@404 265
Chris@404 266 /resize <w> <h>
Chris@404 267 /resize pane <h>
Chris@404 268
Chris@404 269 Resize the main window to width <w> and height <h> (if the
Chris@404 270 window system permits); resize the current pane to height <h>
Chris@404 271 if possible (!!! not yet working).
Chris@404 272
Chris@404 273 /quit
Chris@404 274
Chris@404 275 Exit the program abruptly without saving.
Chris@404 276
Chris@404 277 Handy things still missing from the OSC interface include:
Chris@404 278
Chris@404 279 * the ability to run transforms with non-default parameters or
Chris@404 280 starting from different source models
Chris@404 281 * the ability to add layers to a pane (without transform)
Chris@404 282 * the ability to add panes (and layers) showing any but the
Chris@404 283 main model
Chris@404 284 * the ability to set play parameters on a layer/model and show/hide it
Chris@404 285 * the ability to set the vertical zoom range (vital for spectrogram)
Chris@404 286 * the ability to import and export layers
Chris@404 287 * a working pane resize
Chris@404 288 * quick shortcuts to Melodic Range Spectrogram, Peak Frequency Spectrogram
Chris@404 289 * the ability to rename a layer
Chris@404 290
Chris@404 291