Plugin Development Tutorial
- Familiarity with C++ is required.
- Follow the Setting up your development environment section of the Rack README.
- If you would like to build Rack from source, continue to the https://github.com/VCVRack/Rack#building section of the Rack README.
- If you would like to save time, you may skip building Rack and use the Rack SDK instead. You can then run your plugin with an official build of Rack.
Clone the VCV Template plugin in a
plugins/ directory to get started. Familiarize yourself with the file structure.
Makefile: The build system configuration file. Edit this to add compiler flags and custom targets.
src/: C++ and C source files
Template.cpp / Template.hpp: Plugin-wide source and header for plugin initialization and configuration. Rename this to the name of your plugin.
MyModule.cpp: A single module's source code. Duplicate this file for every module you wish to add. You may have multiple modules per file or multiple files for a single module, but one module per file is recommended.
res/: Resource directory for SVG graphics and anything else you need to
LICENSE.txt: The template itself is released into public domain (CC0), but you may wish to replace this with your own license.
The Template plugin implements a simple sine VCO, demonstrating inputs, outputs, parameters, and other concepts.
Inputs, Outputs, Parameters, and Lights
Decide how many components you need on the panel of your module.
Change the names of inputs, outputs, params, and lights in the enums in the
MyModule class of
Write the DSP code of your module in the
MyModule::step() function, using the values from the
Rack includes a work-in-progress DSP framework in the
include/dsp/ directory that you may use.
Writing a high quality audio processor is easier said than done, but there are many fantastic books and online resources on audio DSP that will teach you what you need to know.
My word of advice: mind the aliasing.
Design your module's panel with a vector graphics editor and save it to the
res/ directory as an SVG file.
Inkscape is recommended, but Adobe Illustrator, Affinity Designer, Gravit Designer, etc. may also work.
Make sure the path to the .svg file is correctly specified in the
setPanel(SVG::Load(...)) function in your
Rack renders SVGs at 75 DPI, and the standard Eurorack 1HP module size is 128.5mm x 5.08mm, 5.06" x 0.2", or 380px x 15px.
Note: The Rack renderer is currently only capable of rendering path and group objects with solid fill and stroke. Gradients are experimental and might not work correctly. Text must be converted to paths. Clipping masks, clones, symbols, CSS outside style attributes, etc. are not supported.
Add widgets to the panel including params (knobs, buttons, switches, etc.), input ports, and output ports.
createOutput() are used to construct a particular
Widget subclass, set its (x, y) position, range of values, and default value.
Rack Widgets are defined in
include/app.hpp, and helpers are found in
Note: Widgets from
include/components.hpp using Component Library SVG graphics are licensed under CC BY-NC 4.0 and are free to use for noncommercial purposes.
Contact email@example.com for information about licensing for commercial use.
Eventually, you will need to change the name of your plugin from "Template" to something of your choice.
Decide on a "slug" (case-sensitive unique identifier) for your plugin that only contains letters, numbers, and the characters
It should NEVER change after releasing your plugin, otherwise old patches will break, so choose the slug wisely.
To guarantee uniqueness, it is a good idea to prefix the slug by your name, alias, or company name if available, e.g. "MyCompany-MyPlugin".
- Change references of
#include "Template.hpp"in each of the source files.
- In the
Makefile, change the
The version string of your plugin should follow the form MAJOR.MINOR.REVISION and is placed in your plugin's Makefile.
- Before Rack 1.0, the MAJOR.MINOR version should match the version of Rack your plugin is built for, e.g. 0.5. You are free to choose the REVISION version of your plugin, but it recommended to start counting at 0. For example, MyPlugin 0.5.4 would be compatible with all Rack 0.5.X versions.
- After Rack 1.0, the MAJOR version should match the version of Rack your plugin is built for, e.g. 1. You are free to choose the MINOR.REVISION version of your plugin. For example, MyPlugin 1.4.2 would be compatible with all Rack 1.X versions.
After releasing a version of your plugin, it is recommended to add a git tag to your repository with
git tag X.Y.Z.
Don't forget to edit the
LICENSE.txt file to choose a license of your choice, unless you want to release your plugin into the public domain (CC0).
Before releasing your plugin, read the Rack licenses.
If you are considering "porting" a hardware module to the VCV Rack platform, it is a good idea to ask the creator first. It may be illegal, immoral, or cause unpleasant relationships to copy certain intellectual property without permission.
Make sure the VERSION and SLUG are correct in your Makefile, and run
A ZIP package is generated in
dist/ for your architecture.
If you do not have all platforms for building, other plugin developers will be happy to help you by simply obtaining your source and running
make dist themselves.
If you wish to sell your plugin on the VCV Store, email firstname.lastname@example.org for details.
Since Rack is currently in Beta and moving very quickly, breaking changes may be made to the Rack plugin API. Subscribe to the Plugin API Updates Thread to receive notifications when the Rack API changes or a discussion about a change is being held.