vcontrol uses standard, open technologies wherever possible. These include JSON, zero-configuration networking, TCP/IP, C/C++, and open source licensing.
Libvcontrol is a dynamic library that manages all the modules connected to the vcontrol system. If you are making a module, you typically do not need to make libvcontrol. Typically, any control surface system using the vcontrol system will install libvcontrol.
VControl modules are software or hardware modules that have one or more controls that can be adjusted to any float value from 0.0 to 1.0 and/or text value. Modules may also have meters which are handled separately. vcontrol provides a dynamic library named libvcontrol that any number of modules can connect to. A module uses the VControl API to specify a set of controls available to be remotely controlled. The module must provide a callback function so that VControl can set a control value in response to a control surface. And the module must update VControl of any changes to a control value so that a control surface can update its display. A module can be comprised of submodules for flexible control management. A module can provide rich metadata that describes the controls and meters so that surfaces can automatically provide a quality user experience. For example, an EQ plug-in can easily attach metadata to controls so that a surface knows which controls are for which EQ band and EQ function.
Vcontrol lets you create modules that are children of other modules. You can create any hierarchy. This is most useful for larger applications that have sets of features that make sense to group into submodules. An example is an audio workstation. It will typically have a transport submodule, a mixer submodule with an array of track submodules, and more. See the sample code in appmodule.h/cpp.
If an application has a large number of identical submodules, it can make sense to make them submodules of a module array. An example is an audio mixer that can have a huge set of audio track submodules. By using an array module it can greatly simplify things because arrays have an inherent ordering and numerical indexing. See the sample code in appmodule.h/cpp.
Every module must have an Id. The Id is a text value. For example, if you make an EQ plug-in called CoolQ, the Id should be “coolq”. This Id becomes the base value for control Ids that are used by a control surface. If you publish multiple CoolQ instances that operate together as part of a module array, all instances have the same identifier. The concept is similar to a bundle indentifier used in iOS/Mac OS programming. The Id should not contain the manufacturer name.
When controls are added to a module, each control must have a unique identifier. For example, an input gain control might use an Id = “input/gain” and an output gain control uses Id = “output/gain.” These values should be readable and use a path-style format to organize controls into logical sets. The idea is similar to how OSC uses a path to identify a control. However, vcontrol is designed such that long control identifiers do not degrade network messaging performance. MAKE THEM READABLE, THEY CAN BE LONG. The vcontrol system keeps track of all mappings using the Ids. It is important for Ids to not change in the future so that mappings will always just work.
THE ADDITIONAL INFO BELOW IS TYPICALLY FOR DEVELOPERS MAKING A CONTROL SURFACE TO CONTROL MODULES. IF YOU ARE JUST MAKING A MODULE TO CONNECT TO VCONTROL, YOU TYPICALLY DO NOT NEED TO READ FURTHER.
Surface – VControl Hubs
VControl hubs are software or hardware that interface control surfaces to libvcontrol and thus, the apps and modules managed by libvcontrol. A hub uses TCP/IP networking to interface to libvcontrol. A hub publishes a Bonjour service of type _vcontrol-hub.tcp. All instances of libvcontrol listen for that service and when it is detected, instances connect to it. The hub implementation will typically map/adapt the module controls to the surface controls of some hardware controller. For example, a surface might have just one knob, a button, and an LCD display. The hub, thus, must provide a means to select between modules and select which control of a module is mapped to the knob, for example. There is no limitation to how small, large, simple, or complex the hub might be designed. This library provides the basic hub functionality that makes it easy to build any sort of control surface system.
Module Control Ids
Surfaces will send and receive messages to modules to control them. To address modules and parameters, every control will have a control Id. The Id is a composite value of the vendor Id, module Id, and control Id. It looks like a path, such as coolsoftwareinc/coolq/input/gain.