NEYRINCK
DEVELOPER
vcontrol

modern, simple,
open source

vcontrol

For the past several years most media technologies have seen amazing innovation. Faster, better, and cheaper. But not control surfaces. It is like using a rotary-dial telephone in 2015. Control surfaces are stuck using old, awful protocols. Control surface makers can not innovate. Software developers can not innovate. Users

vcontrol solves all these problems.

vcontrol is an open source software system that makes it easy to control any software or hardware plug-in/app/synth/widget with a remote control surface. For example, an audio EQ plug-in used in a digital audio workstation will have frequency, bandwidth, and boost/cut controls. When the plug-in configures as a vcontrol module, then any vcontrol-compatible control surface can adjust the EQ. One surface might be a touch screen with a graph. Another surface might have knobs arranged like a console channel strip. Another might use hand gestures. vcontrol unleashes innovation for controllers.

It is very easy for software developers to connect their plug-in/app/synth/widget to vcontrol. Just add a couple files to the project, write a few lines of code, and compile. vcontrol works on Mac and PC systems.

The vcontrol system has many benefits not provided by other systems. vcontrol is flexible so any number of control surfaces can control any number of modules. vcontrol uses TCP/IP networking for fast performance and flexible, low-cost setups. vcontrol uses zero-configuration networking making it easy to set up. And vcontrol is implemented with open-source software.

V-Control Pro System Utilizing the vcontrol Technology

Neyrinck V-Control Bundle Infographic

vcontrol Technology

vcontrol uses standard, open technologies wherever possible. These include JSON, zero-configuration networking, TCP/IP, C/C++, and open source licensing.

libvcontrol

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

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.

Submodules

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.

Module Arrays

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.

Module Identifiers

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.

Control Identifiers

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.

Start Developing

It is easy to connect your products to vcontrol and be compatible with the latest, innovative control surfaces. You can download the open source code at github.com/pneyrinck/vcontrol. You can also download open source utilities at github.com/pneyrinck/vcontrol_utils.

The following steps will make your module connect to the libvcontrol shared library which connects modules to control surfaces.

add two files to your module project: /module/vcinterface.c, includes/vcontrol.h
option 1 – use a helper class

if your project is an audio plug-in (Audio Unit, AAX, VST, Juce), you can use one of the helpers in /module/helpers to connect your plug-in with one or two lines of code and you are finished.
option 2- use the vcontrol API directly

call VControlModuleCreate(…)
set up the module parameters with VControlModuleAddControl(…)
set up a callback function with VControlModuleSetControlCallback(…)
call VControlModulePublish(…)
call VControlModuleUpdateControlValue(…) any time the module parameters are changed.
respond to the SetControlCallback to set parameters.
there are additional API you can optionally use to provide a richer control experience for users controlling it remotely.

ADDITIONAL NOTE FOR AUDIO PLUG-IN DEVELOPERS

An audio plug-in is a special case for vcontrol because often an audio workstation will have many instances of the same plug-in running, such as an EQ on every track. Any plug-in that can have multiple instances running should create a module array which will be a parent module containing one or more submodules that represent each plug-in instance. A module array allows control surfaces to manage all your plug-ins efficiently. Look at he audio helper classes to see example code.

That’s it to connect your module to the vcontrol system and be controllable by control surfaces.

vcontrol Licensing

vcontrol uses the GPL2 license. This means that other open-source, non-commercial products can freely use it. We also provide licensing for closed-source, commercial products. Typically, a commercial license for a vcontrol module is free. A module uses vcontrol only to be controllable by control surfaces. Please contact us for more information to license for your product.

Contact Us

First Name:
Last Name:
Organization:
Email:
Re-enter Email:
Country:
Contact:
Message: