Virtuoso Remote Control API

The Virtuoso Remote Control API allows you to use Virtuoso to control external applications over network, such as a digital audio workstation (DAW) like Ableton Live or FL Studio.

We have gathered a few open source example applications below that implement Remote Control API. These can be used directly to control DAWs, or they can serve as a foundation as you build your own applications for controlling synthesizers or anything else using the Virtuoso instruments. If you just want to play on sounds in your DAW using Virtuoso, start by using one of these! We also encourage you to contribute to their improvement.

If you want to do something else, like integrating Virtuoso with a modular synthesizer, using the Wavemin to fly a drone, or triggering a light rig with virtual drum pads, see the documentation below and use it to build your own Remote Control application.

And for more help and feedback, please join our Discord!

Example Applications

These are some applications that use the Virtuoso Remote Control API. Please contact us if you’ve developed your own application and would like it listed here!

Virtuoso MIDI Companion

A standalone application that listens to Remote Control messages from Virtuoso and converts them to MIDI using a virtual MIDI port. This is the successor to the MIDI Companion App. It is open source, so you can develop it further with your own features or port it to new platforms that are not yet supported. If you want to control your DAW using Virtuoso, this is a great place to start!

Virtuoso VST Companion

A VST3 plugin that listens to Remote Control messages from Virtuoso and converts them to MIDI directly inside your DAW. This plugin works well in some DAWs but has a few notable limitations and quirks in others, depending on how the DAW implements the VST3 format. It might serve as an example for how to implement the Remote Control API in an audio application using JUCE and C++.

DOCUMENTATION - API Version 0

Virtuoso uses OSC (Open Sound Control) to send messages over network to any other machine. When Remote Control is enabled in Track Settings inside Virtuoso, all instruments will stop playing sounds and will instead send OSC messages that external applications can use to trigger synthesizers or effects. Some aspects of Virtuoso will transform, it will no longer be possible to use the Looper or Tape Recorder, and the instrument UIs will change to reflect generically numbered channels and parameters instead of specific sounds and effects.

The documentation that follows is aimed at explaining how to use the OSC messages inside your own Remote Control enabled applications or plugins. For details on how to use the different example projects to control sound outside of Virtuoso, see their respective README files on GitHub, in the projects linked above.

For more information on the Open Sound Control format, see Wikipedia.

OSC message structure

The OSC messages that Virtuoso sends out consists of an OSC address in three parts:
* The client name - for uniquely identifying which Virtuoso instance is sending the message, this is whatever the user chooses as the client name inside the Remote Control panel in Virtuoso
* The instrument name (such as “board” or “wavemin”) or “global” - for identifying what instrument the message comes from or if it is a global message
* The method name - for identifying what the message does, such as playing a note or setting a parameter

Each OSC message also contains a data array, also consisting of three parts. These are usually used to communicate note numbers, parameter values, channel or anything else relevant to the specific message.

For example, a message could look like this:
Address: “/virtuoso/rimba/noteon”
Data: { 0.63, 5, 60 }

The above would mean that inside Virtuoso, the user has played note 60 (middle C) on the Rimba, set to channel 5, and that the hit velocity was 63% of maximum. An application on the other end can then map this to for example a sampler with a hang drum sound on channel 5, and have it play back middle C at 63% velocity or volume.

Below is a full list of all OSC messages Virtuoso sends out, what data they contain, the expected range, and in what format:

* When all notes off is called, parameter ID 123 will be sent with value 0 as this is the default MIDI CC call for all notes off.
** C = 1, Db = 2, D = 4 etc. Each half step up from C doubles the value. A scale containing only C and D would be 5. A scale containing all notes would be 4095. All white keys is 2741 (1 + 4 + 16 + 32 + 128 + 512 + 2048).

Connecting Virtuoso to a companion application

Virtuoso can connect to external applications either by setting a manual IP or using Autoconnect.

In Autoconnect mode, Virtuoso will listen to broadcasts over UDP on port 9002, and automatically connect to any application that sends a valid broadcast containing the computer’s IP address. Valid broadcasts are formatted the following way:
VirtuosoCompanion:[ipaddress]

For example:
VirtuosoCompanion:192.168.0.24

Once a broadcast has been received, or the user has entered an IP address manually and pressed connect, Virtuoso will start sending OSC messages to the supplied IP address on port 9003.

In order to receive these messages, the receiving application will need to implement an OSC Receiver that picks up the incoming messages and routes them somewhere useful, for example to specific channels in a DAW or to a synthesizer.

Virtuoso parameter mappings

Below is a list of what parameter numbers are tied to what action inside Virtuoso:

0: No parameter
1: Control Panel 1
2: Control Panel 2
3: Control Panel 3
4: Control Panel 4
5: Control Panel 5
6: Control Panel 6
7: Left hand tilt around Z axis
8: Right hand tilt around Z axis
9: Unused / reserved for later
10: Unused / reserved for later
11: Left controller position X (used by Wavemin)
12: Left controller position Y (used by Wavemin)
13: Left controller position Z (used by Wavemin)
14: Right controller position X (used by Wavemin)
15: Right controller position Y (used by Wavemin)
16: Right controller position Z (used by Wavemin)
17: Left thumbstick X axis
18: Left thumbstick Y axis
19: Right thumbstick X axis
20: Right thumbstick Y axis