Chris@404: Chris@404: OSC control of Sonic Visualiser Chris@404: =============================== Chris@404: Chris@404: Sonic Visualiser can be controlled remotely using the Open Sound Chris@2521: Control protocol. This facility requires the Chris@2521: [liblo](http://liblo.sourceforge.net/) (Lite OSC) library by Steve Chris@2521: Harris and Stephen Sinclair to have been available when Sonic Chris@2521: Visualiser was built. Chris@404: Chris@2520: Sonic Visualiser opens a single OSC port on startup, provided that OSC Chris@2520: support is compiled in, the `--no-osc` command-line option has not Chris@2520: been supplied, and permission to use the network was not refused by Chris@2520: the user the first time Sonic Visualiser was run. Chris@2520: Chris@2520: The URL of the OSC port is printed to standard output on startup, or Chris@2520: can be read from the About box on the Help menu. Chris@2520: Chris@2520: Chris@2520: General outline Chris@2520: --------------- Chris@404: Chris@404: OSC commands accepted by Sonic Visualiser take the form: Chris@404: Chris@2520: ``` Chris@2520: ://:/ [ ...] Chris@2520: ``` Chris@404: Chris@2520: For example, `osc.udp://localhost:12654/play 2.0` will play the Chris@404: current session from time 2.0 seconds. Chris@404: Chris@404: Methods that manipulate panes or layers act on the currently selected Chris@2520: pane or layer. Use the `setcurrent` method to choose the right target Chris@404: for subsequent such methods. Chris@404: Chris@2520: Chris@2520: OSC clients and invocation Chris@2520: -------------------------- Chris@2520: Chris@495: If you need an OSC client, there is a small program in the svcore Chris@2520: library at `svcore/data/osc/sv-osc-send.c` that sends an OSC method Chris@2520: and arguments to a given URL -- this is not specific to SV but will Chris@2520: work with it. To compile that program you should only have to run Chris@495: Chris@2520: ``` Chris@2520: $ gcc sv-osc-send.c -o sv-osc-send -llo Chris@2520: ``` Chris@495: Chris@495: provided you have liblo installed. Chris@495: Chris@495: Then there is a small shell script in the same directory, called Chris@2520: `sv-command`, that provides a basic command shell for Sonic Chris@2520: Visualiser. Start SV first, then `sv-command` should find its OSC Chris@2520: port from the system process table when you start it. For example: Chris@495: Chris@2520: ``` Chris@2520: $ PATH=.:$PATH ./sv-command # Set PATH so it can find sv-osc-send Chris@2520: /open snare_hex.wav Chris@2520: /add spectrogram Chris@2520: /set layer Colour Sunset Chris@2520: /play Chris@2520: /quit Chris@2520: $ Chris@2520: ``` Chris@404: Chris@2520: You can also start Sonic Visualiser directly in "OSC script" mode by Chris@2520: supplying the `--osc-script ` command-line option. The Chris@2520: argument to this should be the path of a text file containing a series Chris@2520: of OSC commands (like those in the example above). These will be Chris@2520: executed in succession as quickly as possible. A line that contains Chris@2520: only a number, instead of a command, will cause SV to pause for that Chris@2520: number of seconds before going on with the script. Lines beginning Chris@2520: with `#` are ignored. Chris@404: Chris@2520: If you supply "-" as the filename argument to the `--osc-script` Chris@2520: option, SV will instead read OSC commands from standard input. So you Chris@2520: can do something like Chris@404: Chris@2520: ``` Chris@2520: $ rlwrap sonic-visualiser --osc-script - /path/to/filename.wav Chris@2520: ``` Chris@404: Chris@2520: to obtain a rather limited Sonic Visualiser OSC read-eval loop. Chris@404: Chris@404: Chris@2520: Method reference Chris@2520: ---------------- Chris@404: Chris@2520: ### File management Chris@404: Chris@2520: ``` Chris@2520: /open Chris@2520: ``` Chris@404: Chris@2520: Open a new file (of type determined by Sonic Visualiser). If it is an Chris@2520: audio file, use it to replace the existing main audio file (if any). Chris@404: Chris@2520: ``` Chris@2520: /openadditional Chris@2520: ``` Chris@404: Chris@2520: Open a new file. If it is an audio file, open it in a new pane in Chris@2520: addition to the existing audio file (if any). Chris@404: Chris@2520: ``` Chris@2520: /recent Chris@2520: /last Chris@2520: ``` Chris@404: Chris@2520: Open the ``th most recent file from the Recent Files menu, counting Chris@2520: from 1 for the most recent file opened. "last" is a synonym for Chris@2520: "recent 1". Chris@404: Chris@2520: ``` Chris@2520: /save Chris@2520: ``` Chris@2242: Chris@2520: Save the current session in `` as an SV session file. Chris@2242: Chris@2520: This action will try to fail rather than overwrite an existing file, Chris@2520: but you probably shouldn't rely on that. Chris@404: Chris@2520: ``` Chris@2520: /export Chris@2520: ``` Chris@404: Chris@2520: Export the main audio file to `` in floating-point extended Chris@2520: WAV format. If a region is selected, export only that region. Chris@404: Chris@2520: This action will try to fail rather than overwrite an existing Chris@2520: file, but you probably shouldn't rely on that. Chris@404: Chris@2520: ``` Chris@2520: /exportlayer Chris@2520: ``` Chris@404: Chris@2520: Export the current layer to ``. See `/setcurrent` for how to Chris@2520: change which layer is current. The format to use is determined from Chris@2520: the file extension of ``: Chris@404: Chris@2520: * `xml`, `svl` - Sonic Visualiser layer file formats Chris@2520: * `mid`, `midi` - MIDI (note layers only) Chris@2520: * `ttl`, `n3` - Audio Features Ontology RDF/Turtle (only some layer types) Chris@2520: * `csv` - Comma-separated text Chris@2520: * anything else - Tab-separated text Chris@404: Chris@2520: If a region is currently selected, and the file type is CSV, Chris@2520: tab-separated, or MIDI, export only that region. Otherwise export Chris@2520: the whole layer. Chris@404: Chris@2520: This action will try to fail rather than overwrite an existing Chris@2520: file, but you probably shouldn't rely on that. Chris@404: Chris@2520: ``` Chris@2520: /exportimage Chris@2520: ``` Chris@404: Chris@2520: Export a PNG image of the contents of the current pane to Chris@2520: ``. See `/setcurrent` for how to change which pane is Chris@2520: current. If a region is currently selected, export only that Chris@2520: region. Otherwise export the whole pane. Currently the export will Chris@2520: fail if the area to be exported is more than 32767 pixels wide. Chris@404: Chris@2520: To export to an image of a fixed width regardless of model duration, Chris@2520: consider using `/zoom fit` to zoom the model contents to fit the Chris@2520: window width, then optionally zooming in or out a known number of Chris@2520: steps, before exporting. Chris@404: Chris@2520: This action will try to fail rather than overwrite an existing file, Chris@2520: but you probably shouldn't rely on that. Chris@404: Chris@2520: ``` Chris@2520: /exportsvg Chris@2520: ``` Chris@404: Chris@2520: Export a SVG vector graphic of the contents of the current pane to Chris@2520: ``. See `/setcurrent` for how to change which pane is Chris@2520: current. If a region is currently selected, export only that Chris@2520: region. Otherwise export the whole pane. Chris@404: Chris@2520: This action will try to fail rather than overwrite an existing file, Chris@2520: but you probably shouldn't rely on that. Chris@404: Chris@404: Chris@2520: ### Playback control Chris@404: Chris@2520: ``` Chris@2520: /jump Chris@2520: /jump end Chris@2520: /jump selection Chris@2520: ``` Chris@404: Chris@2520: Jump the playback position to time `` (in seconds); or to the end Chris@2520: of the file; or to the start of the current selection. Chris@404: Chris@2520: ``` Chris@2520: /play Chris@2520: /play Chris@2520: /play selection Chris@2520: ``` Chris@404: Chris@2520: Start playback. If a time `` is given, start from that time in Chris@2520: seconds. If the word `selection` is given instead, play the current Chris@2520: selection. Chris@404: Chris@2520: ``` Chris@2520: /stop Chris@2520: ``` Chris@404: Chris@2520: Stop playback. Chris@404: Chris@2520: ``` Chris@2520: /loop on Chris@2520: /loop off Chris@2520: ``` Chris@404: Chris@2520: Switch playback loop mode on or off. Chris@404: Chris@404: Chris@2520: ### Panes, layers, and the window Chris@404: Chris@2520: ``` Chris@2520: /add Chris@2520: /add Chris@2520: ``` Chris@404: Chris@2520: Add a new pane containing a layer of the given type, based on the Chris@2520: given channel of the main audio file (numbered from 0). If no Chris@2525: `` is specified, mix all channels. The specified layer is Chris@2525: made the current layer, and the new pane becomes the current pane. Chris@404: Chris@2520: Useful values of `` are: Chris@404: Chris@2520: ``` Chris@2520: waveform Chris@2520: spectrogram Chris@2520: melodicrange Chris@2520: peakfrequency Chris@2520: spectrum Chris@2520: timeruler Chris@2520: ``` Chris@404: Chris@2520: The following ``s are also accepted: Chris@404: Chris@2520: ``` Chris@2520: timeinstants Chris@2520: timevalues Chris@2520: notes Chris@2520: text Chris@2520: colour3dplot Chris@2520: ``` Chris@404: Chris@2520: But they are less useful, as they create empty layers which there is Chris@2520: currently no OSC support for editing. Chris@404: Chris@2520: ``` Chris@2520: /setcurrent Chris@2520: /setcurrent Chris@2520: ``` Chris@404: Chris@2520: Make the given `` (a number counting from 1 for the topmost Chris@2520: pane) and optionally the given `` on that pane (a number Chris@2520: counting from 1 for the "frontmost" layer) the current pane and layer Chris@2520: for subsequent pane and layer operations. Chris@404: Chris@2520: ``` Chris@2520: /delete pane Chris@2520: /delete layer Chris@2520: ``` Chris@404: Chris@2520: Delete the current pane or layer. Chris@404: Chris@2520: ``` Chris@2520: /set Chris@2520: /set pane Chris@2520: /set layer Chris@2520: ``` Chris@404: Chris@2520: Set a main window control; a property of the current pane; or a Chris@2520: property of the current layer. Chris@404: Chris@2520: Accepted main window controls are: Chris@404: Chris@2520: * `gain` - whose values are linear multipliers (i.e. 1.0 == unity gain). Chris@2520: * `speed` - takes a value of a percentage change in playback speed, Chris@2520: so 100 is the default playback speed, 200 sets double the default Chris@2520: speed, and 50 sets half the default. Chris@2520: * `overlays` - controls the verbosity level of the text overlays on Chris@2520: each pane, from 0 (everything off) to 2 (everything on). Chris@2520: * `zoomwheels` - controls whether the zoom wheels are displayed (1) Chris@2520: or not (0). Chris@2520: * `propertyboxes` - controls whether the property boxes are displayed Chris@2520: (1) or not (0). Chris@404: Chris@2520: For pane and layer properties, the control name is the displayed name Chris@2520: of the given property (though you may use "-" or "_" in place of any Chris@2520: spaces in the name if it's easier for you). The value may be the Chris@2520: displayed value or underlying integer for the property. Chris@404: Chris@2520: Some examples: Chris@2520: Chris@2520: ``` Chris@2520: /set pane Global-Scroll off Chris@2520: /set pane Follow_Playback Scroll Chris@2520: /set layer Colour Blue Chris@2520: /set layer Scale-Units dB Chris@2520: /set layer Frequency-Scale Log Chris@2520: ``` Chris@2520: Chris@2520: Note that while you can use "-" or "_" in place of spaces in the Chris@2520: property name, you cannot currently do so in the value text. If Chris@2520: this is a problem for you, you might be able to set the value Chris@2520: as an integer instead (all layer properties can be set this way). Chris@2520: Chris@2520: ``` Chris@2520: /zoom Chris@2520: /zoom in Chris@2520: /zoom out Chris@2520: /zoom fit Chris@2520: /zoom default Chris@2520: ``` Chris@2520: Chris@2520: Zoom to a given zoom ``, given in audio sample frames per Chris@2520: pixel; or zoom in or out one step from the current level; or zoom so Chris@2520: that the whole model duration fits in the current view width; or Chris@2520: return to the default zoom level. This method acts on the current Chris@2520: pane (it only affects all panes if set to Global Zoom, which is the Chris@2520: default). Chris@2520: Chris@2520: ``` Chris@2520: /zoomvertical Chris@2520: /zoomvertical in Chris@2520: /zoomvertical out Chris@2520: /zoomvertical default Chris@2520: ``` Chris@2520: Chris@2520: Change the vertical zoom and origin so as to show the value range from Chris@2520: `` to `` in the vertical scale; or zoom in or out Chris@2520: vertically; or return to the default vertical zoom level. The effect Chris@2520: of this method is heavily dependent on the current layer. Chris@2520: Chris@2520: ``` Chris@2525: /resize Chris@2525: ``` Chris@2525: Chris@2525: Resize the main window to width `` and height `` (if the window Chris@2525: system permits). Chris@2525: Chris@2525: Chris@2525: ### Region selection Chris@2525: Chris@2525: ``` Chris@2525: /select Chris@2525: /select all Chris@2525: /select none Chris@2525: ``` Chris@2525: Chris@2525: Select the region from times `` to `` in seconds; or select Chris@2525: the whole file; or clear the selection. If there is a layer selected Chris@2525: that can be used as a snap guide for the selection, then the selection Chris@2525: will be snapped to it (in the same manner as when making selections Chris@2525: interactively). Chris@2525: Chris@2525: ``` Chris@2525: /addselect Chris@2525: ``` Chris@2525: Chris@2525: Make an additional selection (leaving any existing selection in place) Chris@2525: from times `` to `` in seconds. Chris@2525: Chris@2525: Chris@2525: ### Feature extraction Chris@2525: Chris@2525: ``` Chris@2520: /transform Chris@2520: ``` Chris@2520: Chris@2520: Transform the current main audio file using the named transform. Chris@2520: Transforms are named according to the scheme Chris@2520: Chris@2520: ``` Chris@2520: type:source:plugin:output Chris@2520: ``` Chris@2520: Chris@2520: For example, the percussion onset detector from the Vamp example Chris@2520: plugin set can be invoked via Chris@2520: Chris@2520: ``` Chris@2520: /transform vamp:vamp-example-plugins:percussiononsets:onsets Chris@2520: ``` Chris@2520: Chris@2520: If the output is omitted, the first is used. Note that you need to Chris@2520: use the plugin and output name, not description: in this case Chris@2520: `percussiononsets` rather than "Simple Percussion Onset Detector". Chris@2520: Chris@2520: There is not yet any way to run a transform via OSC on any but the Chris@2520: main audio file, nor with any but its default parameters, processing Chris@2520: block/step size, or channel selection. Chris@2520: Chris@2520: Chris@2520: ### Housekeeping Chris@2520: Chris@2520: ``` Chris@2520: /undo Chris@2520: /redo Chris@2520: ``` Chris@2520: Chris@2520: Undo the last editing operation; redo the last undone operation. Note Chris@2520: that most of the classic editing operations (copy and paste etc) are Chris@2520: not controllable via OSC, but undo may still be useful because Sonic Chris@2520: Visualiser considers actions such as adding a pane to be undoable Chris@2520: editing operations as well. Chris@2520: Chris@2520: ``` Chris@2520: /quit Chris@2520: ``` Chris@2520: Chris@2520: Exit the program abruptly without saving. Chris@2520: Chris@2520: Chris@2520: ### Missing things Chris@2520: Chris@2520: Handy features still missing from the OSC interface include: Chris@404: Chris@404: * the ability to run transforms with non-default parameters or Chris@404: starting from different source models Chris@404: * the ability to add layers to a pane (without transform) Chris@404: * the ability to add panes (and layers) showing any but the Chris@404: main model Chris@404: * the ability to set play parameters on a layer/model and show/hide it Chris@2520: * the ability to import layers Chris@404: * a working pane resize Chris@404: * the ability to rename a layer Chris@404: Chris@404: