Table of Contents

Introduction 1.1
Quick Start 1.2

Installing 1.3

FAQ 1.4
Core 1.5

Plugin Development 1.6

Tutorial 1.6.1
Voltage Standards 1.6.2

DSP 1.6.3
Rack Development 1.7
Architecture 1.7.1

Contributing 1.7.2
Glossary 1.8
Edit on GitHub 1.9

1
Introduction

VCV Rack Manual

The VCV Rack manual is under active development.

Edit this manual at https://github.com/VCVRack/manual.

PDF download

2
Quick Start

Quick Start
Once Rack is installed and launched (see Installing), you will see an empty rack with a toolbar.

Add a module by right-clicking on an empty space on the rack, or simply press <enter> . Select the Core plugin and then Audio
to connect Rack to an audio output on your computer.

3
Quick Start

You can move the module around the rack by clicking and dragging an empty space on its panel. Select an audio driver and
device by clicking on Audio's digital display.

4
Quick Start

Continue adding more modules, such as VCO-1 and Mixer from the Fundamental plugin. Connect a cable from the SIN output of
the VCO-1 to the input of the Mixer by clicking and dragging from one of the ports.

Connect another cable from the Mixer output to the first channel of Audio's "output" section, and add another cable to the second
channel. You can stack multiple cables on output ports by dragging from an input to an output, or by Ctrl-clicking (Cmd-clicking
on MacOS) from an output to an input.

5
Quick Start

Finally, adjust Mixer's first channel or main volume by clicking and dragging the fader or knob upward/downward.

At this point, you are ready to learn the rest of the Fundamental modules to build your own unique patches. I personally
recommend that you attempt to push the Fundamental modules to their limits before moving on to other official or third-party
plugins. They are more capable than they might appear, and learning how to use them effectively will give you more power and
understanding when installing more modules later. When you are ready, install more plugins with the Plugin Manager.

6
Installing

Installing
Download Rack on the VCV Rack website.

Mac
Open the DMG image and copy the Rack app to your Applications folder. You may need to right click the application and click
"Open" when launching for the first time.

Windows
Run the installer, and launch Rack from the Start Menu.

Linux
Unzip the zip file. With your terminal, cd into the Rack directory, and run ./Rack.sh .

Installing plugins
On the VCV Plugin Manager, add each plugin you wish to install. If not logged in to your VCV account, you will be prompted to
log in or register. Once the desired plugins are added to your account, open Rack and log in using the toolbar at the top of the
window. After logging in, click "Update plugins" and the new plugins will be synchronized to your computer.

If your computer is offline, you may download plugins using another computer and transfer the Rack/plugins folder to the
offline computer.

Installing plugins not available on the Plugin Manager

Install third-party plugins at your own risk. Like VST plugins, installing plugins from unknown sources may compromise your
computer and personal information.

Download the plugin ZIP package from the vendor's website to <Rack local directory>/plugins (See Where is ?). Rack will
extract and load the plugin upon launch.

Note: Do not download the plugin via GitHub's green "Clone or download" button. These are source code ZIP packages and do
not contain the compiled plugin binary. If the vendor distributes their plugin with GitHub, look in the "Releases" section for the
compiled ZIP packages.

7
FAQ

FAQ
When will Rack 1.0 be ready?
Rack is currently in Beta (thus the version 0.x), so by using it, you are an "early tester". Don't worry, Rack 1.0 will also be free
open-source software.

In order for Rack to earn its "1.0" designation, it must improve in the following three fronts.

Compatibility
Since I am an "indie developer", I cannot yet afford to test Rack on every combination of hardware on the market. With the
introduction of commercial VCV plugin sales, I will soon be able to invest in hardware that is known to have compatibility
problems with Rack. If you are willing to lend me hardware to test, email [email protected] for details.

Stability
Rack is not ready to be trusted for live use, although some musicians have used it successfully in live performances. In order for
Rack to be considered "stable", it must produce audio with no clicks or pops on modern hardware for several minutes and must
crash less than once per several days of continuous use. Currently, stability in Rack is the most developed among these three
fronts.

Performance
Depending on your CPU and graphics card, Rack may consume high CPU/GPU resources and therefore increase your laptop's fan
speed. I am aware of this, so there is no need to inform me.

To answer the original question, there is currently no time estimate for 1.0.

My audio interface / MIDI device doesn't work.

Make sure the device drivers are up to date for your operating system. If this does not solve it, please refrain from notifying me
unless you

are willing to lend me your audio interface (email [email protected] for more details), or
you are a developer and have discovered a fix to the source code of Rack, RtAudio (use rtaudio_test to determine whether the
issue is with Rack or RtAudio), or RtMidi.

See Compatibility above.

The graphics are rendered incorrectly, not at all, or Rack doesn't launch because of an
"OpenGL error".
Rack requires at least OpenGL 2.0 with the GL_EXT_framebuffer_object extension. If your graphics card supports this, make
sure you've installed the latest graphics drivers, and restart Rack. If this does not fix it, see below for instructions on submitting a
bug to Rack's issue tracker.

See Compatibility above.

The CPU usage is high.

See Performance above.

8
FAQ

I found a bug.
Search Rack's issue tracker to check whether someone else has posted a similar issue. If you think your problem is unique
(unlikely but possible), you may open an issue or email [email protected] with a detailed report containing the following
information.

Your operating system and version

The Rack version
The actions that trigger the problem
Any error messages that appear. Screenshots are helpful.
The hardware (e.g. audio interface, MIDI device, graphics card) related to your problem

I have a feature request.

After searching Rack's issue tracker, you may open an issue or email [email protected] with the following information.

Your proposal, with consideration for how it fits into Rack's existing features
A possible workflow or diagram (if your request involves multiple steps or UI states, e.g. dragging multiple modules
simultaneously).

Depending on the usefulness of your request, it may take 15 minutes or 24 months for your feature to be added, or the issue may
be closed if there is little total benefit compared to the cost of implementation (time saved or spent using the feature, divided by
the time to develop the feature).

How do I load a default patch when selecting File > New?

Save a patch to <Rack local directory>/template.vcv , and it will be loaded after clearing the rack.

Where is \?
MacOS: Documents/Rack/

Windows: My Documents/Rack/

Linux: ~/.Rack/

9
Core

Core
The Core plugin is actually not a plugin at all. It's built in to the Rack application itself, but you can add Core modules to your
rack just like normal modules.

Audio

The Audio module merges the virtual Rack world with the physical hardware world. The INPUT section sends up to 8 Rack
signals to a hardware audio device for playback, and the OUTPUT section sends up to 8 hardware signals into Rack.

Audio currently supports the following drivers.

Core Audio on Mac

WASAPI and ASIO on Windows
ALSA on Linux
VCV Bridge (described in a below section) on all OS's, although there are no Bridge plugins for Linux at this time

After a driver is selected, a particular device can be chosen for the driver. If the device has more than 8 inputs or outputs, you can
select the desired range of outputs, offset by a factor of 8.

The sample rate is the number of audio samples per second for the audio device to process. Note that this rate is different than
Rack's internal sample rate set from the toolbar at the top of the screen, which determines the number of samples per second for
virtual Rack modules to process. If set to different rates, sample rate conversion will occur, resulting in slightly higher CPU usage,
slightly less audio fidelity, and slightly more latency.

The block size sets the number of samples to store in the audio buffer before releasing to the audio device. A higher size results in
more latency ( blockSize / sampleRate seconds), but a lower size requires your operating system to communicate with the
audio device more frequently, resulting in potentially less audio stability. A good balance can be found by increasing the block
size until no audio "glitches" are heard.

10
Core

Note: Using multiple Audio modules is experimental and may crash Rack or render unstable audio. Most DAWs avoid this feature
entirely by restricting audio to a single input and a single output device for stability reasons, but if using multiple audio devices in
Rack works with your configuration, more power to you!

MIDI-1

Coming soon

MIDI-4

11
Core

Coming soon

MIDI-CC

Coming soon

MIDI-Trig

Coming soon

12
Core

Blank

Useful for adding space between modules in your rack. You can resize the panel by dragging the edges horizontally, with a
minimum size of 2HP.

Notes

Useful for adding patch notes, section titles for organization, instructions, and author information to your patches. You can copy
and paste text with Ctrl+C and Ctrl+V.

13
Core

VCV Bridge
Rack is a standalone DAW-like application and not a VST/AU plugin because of the major limitations of these formats. It is
common to think of physical modular synthesizers as entire self-contained DAWs, and many people use Rack as a complete
DAW to compose music and build patches without other software.

However, VCV Bridge allows audio and MIDI to be transferred between Rack and your DAW through the included VST/AU
Bridge plugin. Currently VCV Bridge is only a VST/AU effect plugin (Mac and 32/64-bit Windows) for using Rack as a
send/return on a DAW track. VSTi/AU instrument plugins, MIDI, and DAW clock transport are coming soon in a later Rack 0.6.*
update.

Setting up Bridge in Rack and your DAW is easy, and setup order between the two applications does not matter.

Setting up Bridge in your DAW

Make sure the VST or AU Bridge plugin is installed, and launch your DAW.
Add the "VCV Bridge" effect plugin to an audio track.
Open the plugin parameters (e.g. by clicking the plugin's triangle arrow in Ableton Live) to reveal the Bridge port setting and
16 automation parameters.

Setting up Bridge in Rack

Add an Audio or MIDI module to Rack (from the Core plugin), and select "Bridge" from the driver dropdown list.
Open the device menu to select the Bridge port.

Up to 8 channels of audio entering the Bridge effect plugin are routed to the INPUT section of the Audio module in Rack and then
back to the effect plugin.

The 16 automation parameters in the VST/AU Bridge plugin simply generate MIDI-CC messages 0-15, so you can use a Core
MIDI-CC interface to convert them to 0-10 V signals in Rack.

14
Tutorial

Plugin Development Tutorial

Prerequisites
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.

Template Plugin
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 fopen()

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 MyModule.cpp .

DSP
Write the DSP code of your module in the MyModule::step() function, using the values from the params , inputs , and
outputs vectors. 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.

Panel
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 ModuleWidget constructor. 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.

Component Widgets

15
Tutorial

Add widgets to the panel including params (knobs, buttons, switches, etc.), input ports, and output ports. Helper functions
createParam() , createInput() , and 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/widgets.hpp and include/app.hpp , and
helpers are found in include/rack.hpp .

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 protected] for information about licensing for commercial use.

Naming
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".

Rename Template.cpp and Template.hpp .

Change references of #include "Template.hpp" in each of the source files.
In the Makefile , change the SLUG and VERSION .

Versioning
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 .

Licenses
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.

Packaging
Make sure the VERSION and SLUG are correct in your Makefile, and run make dist . 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.

Releasing
To list your plugin on the VCV Plugin Manager, see the VCV community repository README.

16
Tutorial

Maintaining
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.

17
Voltage Standards

Voltage Standards
Rack input and output values (carried by cables) are in voltage units. You can measure absolute voltage levels using the
Fundamental Scope.

Rack attempts to model Eurorack standards as accurately as possible, but this is a problem for two reasons: there are very few
actual "standards" in Eurorack (The only rule is that you can always find a module which breaks the rule), and a few changes must
be made due to using a finite sample rate (digital) vs. an infinite sample rate (analog).

Audio and Modulation

Audio outputs are typically ±5V (before bandlimiting is applied), and CV modulation sources are typically 0 to 10V (unipolar
CV) or ±5V (bipolar CV).

Output Saturation
In Eurorack, power supplies supply -12 to 12V. No voltage should be generated beyond this range, since it would be (mostly)
impossible to obtain in Eurorack. Additionally, protection diodes on the ±12V rails usually drop the range to ±11.7V.

However, if you do not want to model analog output saturation for simplicity or performance reasons, that is perfectly fine. It is
best to allow voltages outside this range rather than use hard clipping with clampf(out, -1.f, 1.f) because in the best case
they will be attenuated by a module downstream, and in the worst case, they will be hard clipped by the Audio Interface.

If your module applies gain to an input, it is a good idea to saturate the output.

Triggers
In Eurorack, many modules are triggered by reaching a particular rising slope threshold. However, because of the Gibbs
phenomenon, a digital emulation will falsely retrigger many times if the trigger source is bandlimited.

Thus, trigger inputs in Rack should use SchmittTrigger from digital.hpp with a low threshold of about 0.1V and a high
threshold of around 1 to 2V. For example, Audible Instruments modules are triggered once the input reaches 1.7V and can only be
retriggered after the signal drops to or below 0V.

Trigger sources should produce 5 to 10V with a duration of 1 millisecond. An easy way to do this is to use PulseGenerator from
digital.hpp .

Pitch
Most Eurorack manufacturers have decided on the 1V/octave standard. The relationship between frequency and voltage is thus f

= f0 * powf(2.f, pitchVoltage) .

If you need a default pitch for your oscillator with initial knob positions and 0V at the pitch input, use C4 ( f0 = 261.626 Hz ).

NaNs and Infinity

If your module might produce NaNs or infinite values with finite input, e.g. an unstable IIR filter or reverb, it should check and
return 0 if this happens: isfinite(out) ? out : 0.f .

18
Glossary

Glossary

Core Audio
https://developer.apple.com/library/content/documentation/MusicAudio/Conceptual/CoreAudioOverview/WhatisCoreAudio/What
isCoreAudio.html

WASAPI
https://msdn.microsoft.com/en-us/library/windows/desktop/dd371455%28v=vs.85%29.aspx

ASIO
A computer sound card driver protocol for digital audio specified by Steinberg, providing a low-latency and high fidelity interface
between a software application and a computer's sound card.

https://en.wikipedia.org/wiki/Audio_Stream_Input/Output

ALSA
http://alsa-project.org/main/index.php/Main_Page

19