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