@@ -40,7 +40,7 @@ pacman -S git wget gcc gdb make cmake tar unzip zip curl jq | |||
## Building Rack | |||
You do not need to build Rack to build plugins if you use the Rack SDK. | |||
*You do not need to build Rack to build plugins if you use the Rack SDK.* | |||
*If the build fails for you, please [report the issue](FAQ.html#i-found-a-bug) to help the portability of Rack.* | |||
@@ -1,23 +0,0 @@ | |||
# Contributing | |||
VCV generally does not accept unpaid code contributions (i.e. pull requests and patches) to Rack due to time costs. | |||
A long-lasting change to Rack's source code is more than just a code patch. Changes usually involve | |||
- research to devise the best solution with a convincing argument | |||
- acceptance of API/ABI change proposals | |||
- generalizability to solve similar issues and flexibility for solving future solutions without a complete rewrite | |||
- future-proofing to avoid unnecessarily breaking patches or API/ABI in the near future | |||
- testing on relevant platforms, hardware devices, plugins, etc. | |||
- dedication to maintain the code in the future | |||
- sometimes legal review | |||
Unpaid contributions typically omit many of the above tasks, making the code more expensive for me to accept than simply writing it myself. Instead, there are many other areas where contributions are much appreciated. | |||
- Dependencies of Rack. Especially [nanovg](https://github.com/memononen/nanovg)'s performance, [rtaudio](https://github.com/thestk/rtaudio)/[rtmidi](https://github.com/thestk/rtmidi)'s stability and compatibility, and maybe even touch support in [GLFW](https://github.com/glfw/glfw). You would be helping many more projects than just Rack. | |||
- Your own Rack [plugin](PluginDevelopmentTutorial.html) | |||
- Maintaining the Rack plugin ecosystem by [curating](https://github.com/VCVRack/community/issues/352), [updating](https://github.com/VCVRack/community/issues/269), and [reviewing](https://github.com/VCVRack/community/issues/354) plugins | |||
- Edits to the [VCV Rack manual](https://github.com/VCVRack/manual). | |||
I will consider your contribution to Rack if you first open a [GitHub issue](https://github.com/VCVRack/Rack/issues) with a detailed design proposal, which may create an open discussion before the change is implemented. | |||
By submitting code through a pull request, you agree to assign the copyright of your code to Andrew Belt to be licensed under the BSD-3-Clause (see [Licenses](https://github.com/VCVRack/Rack#licenses)). |
@@ -1,35 +1,38 @@ | |||
# Core | |||
The *Core* plugin (built into Rack itself) includes utilities and interfaces for interfacing between virtual and hardware realms. | |||
The *Core* plugin (built into Rack itself) includes utilities and interfaces for interfacing between the virtual and hardware world. | |||
- [Audio](#audio) | |||
- [MIDI Interfaces](#midi-interfaces) | |||
- [MIDI-1](#midi-1) | |||
- [MIDI-4](#midi-4) | |||
- [MIDI-CV](#midi-cv) | |||
- [MIDI-CC](#midi-cc) | |||
- [MIDI-Trig](#midi-trig) | |||
- [MIDI-Gate](#midi-gate) | |||
- [MIDI-Map](#midi-map) | |||
- [CV-MIDI](#cv-midi) | |||
- [CV-CC](#cv-cc) | |||
- [CV-Gate](#cv-gate) | |||
- [Blank](#blank) | |||
- [Notes](#notes) | |||
## Audio | |||
 | |||
<img class="module-screenshot" src="https://vcvrack.com/screenshots/Core/AudioInterface.png"> | |||
<img class="module-screenshot" src="https://vcvrack.com/screenshots/Core/AudioInterface16.png"> | |||
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. | |||
The **TO DEVICE** section sends Rack signals to a hardware audio device for playback, and the **FROM DEVICE** section receives hardware signals into Rack. | |||
*Audio* currently supports the following **drivers**. | |||
- [Core Audio](https://developer.apple.com/library/content/documentation/MusicAudio/Conceptual/CoreAudioOverview/WhatisCoreAudio/WhatisCoreAudio.html) on Mac | |||
- [Core Audio](https://developer.apple.com/library/content/documentation/MusicAudio/Conceptual/CoreAudioOverview/WhatisCoreAudio/WhatisCoreAudio.html) on MacOS | |||
- [WASAPI](https://msdn.microsoft.com/en-us/library/windows/desktop/dd371455%28v=vs.85%29.aspx) on Windows | |||
- [ASIO](https://en.wikipedia.org/wiki/Audio_Stream_Input/Output) on Windows | |||
- [ALSA](http://alsa-project.org/main/index.php/Main_Page) on Linux | |||
- [JACK](http://www.jackaudio.org/) on Linux | |||
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](Toolbar.html), which determines the number of samples per second for virtual Rack modules to process. | |||
Note that this rate is different than Rack's [engine sample rate](https://vcvrack.com/manual/MenuBar.html#sample-rate), which determines the number of samples per second for 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. | |||
@@ -43,10 +46,10 @@ Most DAWs avoid this feature entirely by restricting audio to a single input and | |||
## MIDI Interfaces | |||
Each MIDI interface module (described below) supports the following drivers. | |||
- Core MIDI on Mac | |||
- Windows MIDI on Windows | |||
- ALSA on Linux | |||
- JACK on Linux | |||
- [Core MIDI](https://developer.apple.com/documentation/coremidi?language=objc) on MacOS | |||
- [Windows MIDI](https://docs.microsoft.com/en-us/windows/desktop/Multimedia/midi-functions) on Windows | |||
- [ALSA](http://alsa-project.org/main/index.php/Main_Page) on Linux | |||
- [JACK](http://www.jackaudio.org/) on Linux | |||
- Gamepad | |||
- Computer keyboard | |||
@@ -54,40 +57,39 @@ The *gamepad* MIDI driver allows USB video game controllers to be used for CV an | |||
Gamepad buttons are mapped to MIDI note gates starting with `C-1`, `C#-1`, `D-1`, etc. | |||
Joystick axes are mapped to MIDI CC messages starting with `CC0`, `CC1`, `CC2`, etc. with a nonstandard MIDI extension that allows negative CC values to be used. | |||
The *computer keyboard* MIDI driver generates MIDI notes when keys are presses while the Rack window is focused. | |||
The *computer keyboard* MIDI driver generates MIDI notes when keys are presses while the Rack window is focused. | |||
Using four rows of computer keys, the two-row virtual MIDI keyboard spans approximately 2½ octaves and can be shifted down and up with the `` ` `` and `1` keys. | |||
Currently only the QWERTY (US) layout is supported, but other keyboard layouts may function similarly. | |||
The following is the layout for the QWERTY (US) keyboard. | |||
 | |||
 | |||
### MIDI-1 | |||
 | |||
The **CV** output generates a 1V/oct pitch signal of the last held MIDI note. | |||
**GATE** generates 10V when a key is held. It does not retrigger when notes are played legato. | |||
**VEL** generates a CV signal from 0V to 10V of the velocity, **AFT** generates aftertouch CV (channel pressure, not polyphonic aftertouch), **PW** generates pitch wheel CV from -5V to 5V, and **MW** generates mod wheel CV. | |||
**RTRG** generates a 1 ms trigger when a new note is pressed. | |||
**CLK1** and **CLK2** generate triggers specified by the division set by right-clicking on the panel and selecting the *CLK 1 rate* or *CLK 2 rate*. | |||
**STRT**, **STOP**, and **CONT** generate triggers when the MIDI device sends a start, stop, or continue event. | |||
### MIDI-CV | |||
<img class="module-screenshot" src="https://vcvrack.com/screenshots/Core/MIDIToCVInterface.png"> | |||
- **V/OCT** generates a 1V/oct pitch signal of the last held MIDI note. | |||
- **GATE** generates 10V when a key is held. It does not retrigger when notes are played legato. | |||
- **VEL** generates a CV signal from 0V to 10V of the velocity | |||
- **AFT** generates aftertouch CV (channel pressure, not polyphonic aftertouch) | |||
- **PW** generates pitch wheel CV from -5V to 5V | |||
- **MW** generates mod wheel CV. | |||
- **CLK** generates a clock for every [24-PPQN](https://en.wikipedia.org/wiki/Pulses_per_quarter_note) MIDI clock received. | |||
- **CLK/N** generates a clock specified by the division set by right-clicking on the panel and selecting the *CLK/N rate*. | |||
- **RTRG** generates a trigger when a new note is pressed, regardless of legato. | |||
- **STRT**, **STOP**, and **CONT** generate triggers when the MIDI device sends a start, stop, or continue event. | |||
### MIDI-4 | |||
 | |||
Right-click the panel to enable polyphony and select the number of polyphonic channels. | |||
MIDI-4 contains a subset of the outputs from MIDI-1, except that it handles up to four simultaneous notes. | |||
Right-click the panel to select the polyphony mode to specify the behavior in mapping MIDI notes to four channels. | |||
- *Reset*: Each pressed note selects the lowest available channel, or the last channel if none are available. | |||
- *Rotate*: Each pressed note selects the next available channel, or just the next channel if none are available, wrapping around to the first channel after the fourth is reached. | |||
- *Reuse*: If a channel with the same MIDI note has been previously used, reuse it. Otherwise, use the Reset mode behavior. | |||
- *Reassign*: As notes are released, higher channels are reassigned to lower channels if space is available. | |||
- *Unison*: All channels generate the same monophonic signal. | |||
- **Rotate**: Each pressed note selects the next available channel, or just the next channel if none are available, wrapping around to the first channel after the last channel is reached. | |||
- **Reuse**: If a channel with the same MIDI note has been previously used, reuse it. Otherwise, use the Reset mode behavior. | |||
- **Reset**: Each pressed note selects the lowest available channel. Releasing a note shifts all above channels down. | |||
Remember that MIDI interfaces can be used simultaneously with the same driver, for example if global controls like pitch and mod wheel are needed along with polyphonic controls. | |||
Multiple MIDI interfaces may be used simultaneously with the same driver, for example to combine the functionality of MIDI-CV and MIDI-CC. | |||
### MIDI-CC | |||
 | |||
<img class="module-screenshot" src="https://vcvrack.com/screenshots/Core/MIDICCToCVInterface.png"> | |||
Each output maps a MIDI CC (Continuous Controller) messages from 0 to 127 to a CV signal from 0V to 10V. | |||
Some drivers like the gamepad driver generate nonstandard MIDI values from -128 to 127, which is mapped from -10V to 10V. | |||
@@ -98,25 +100,45 @@ A **LRN** indicator is displayed to represent that the port is in "learn" mode. | |||
Either type a number or move a controller to set the CC number. | |||
### MIDI-Trig | |||
 | |||
### MIDI-Gate | |||
<img class="module-screenshot" src="https://vcvrack.com/screenshots/Core/MIDITriggerToCVInterface.png"> | |||
MIDI-Trig is similar to MIDI-CC, except that it generates 10V gate signals when a particular note is held. | |||
MIDI-Gate is similar to MIDI-CC, except that it generates 10V gate signals when a particular note is held. | |||
For MIDI sequencers and drum machines that send immediate note ON/OFF messages in sequence, a 1 ms trigger is produced. | |||
To generate a CV signal corresponding to the velocity of the note instead of 10V, right-click on the panel and enable *Velocity* mode. | |||
This is useful for setting the amplitude of percussive sounds for MIDI controllers with velocity-capable pads, for example. | |||
### MIDI-Map | |||
<img class="module-screenshot" src="https://vcvrack.com/screenshots/Core/MIDI-Map.png"> | |||
TODO | |||
### CV-MIDI | |||
<img class="module-screenshot" src="https://vcvrack.com/screenshots/Core/CV-MIDI.png"> | |||
TODO | |||
### CV-CC | |||
<img class="module-screenshot" src="https://vcvrack.com/screenshots/Core/CV-CC.png"> | |||
TODO | |||
### CV-Gate | |||
<img class="module-screenshot" src="https://vcvrack.com/screenshots/Core/CV-Gate.png"> | |||
TODO | |||
## Blank | |||
 | |||
<img class="module-screenshot" src="https://vcvrack.com/screenshots/Core/Blank.png"> | |||
Useful for adding space between modules in your rack. | |||
You can resize the panel by dragging the edges horizontally, with a minimum size of 3HP. | |||
## Notes | |||
 | |||
<img class="module-screenshot" src="https://vcvrack.com/screenshots/Core/Notes.png"> | |||
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. |
@@ -1,26 +1,5 @@ | |||
# FAQ | |||
## 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 contact@vcvrack.com for more details), or | |||
- you are a developer and have discovered a fix to the source code of Rack, [RtAudio](https://github.com/thestk/rtaudio) (use [rtaudio_test](https://github.com/AndrewBelt/rtaudio_test) to determine whether the issue is with Rack or RtAudio), or [RtMidi](https://github.com/thestk/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. | |||
## I found a bug. | |||
Search [Rack's issue tracker](https://github.com/VCVRack/Rack/issues?q=is%3Aissue) to check if someone else has posted a similar issue. | |||
@@ -43,11 +22,13 @@ If you believe the feature has never been requested before, [create a GitHub acc | |||
Your feature request may be addressed during the next iteration of feature design of Rack. | |||
If your request is judged to be not sufficiently useful to other users, it may be closed. | |||
## How do I load a default patch when selecting File > New? | |||
## The graphics are rendered incorrectly, not at all, or Rack doesn't launch because of an "OpenGL error". | |||
Save a patch to `<Rack local directory>/template.vcv`, and it will be loaded after clearing the rack. | |||
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. | |||
## Where is the "Rack local directory"? | |||
## Where is the "Rack user directory"? | |||
- MacOS: `Documents/Rack/` | |||
- Windows: `My Documents/Rack/` | |||
@@ -70,12 +51,13 @@ It is not planned. There are many issues with such a project. | |||
- The friction for a developer to build and test their plugins on iOS/Android is significantly higher than the three desktop OS's, which may decrease their willingness to develop Rack plugins. | |||
- When serving an app on the App Store or Google Play, Apple and Google are not obligated to continue serving an app and may remove it at will or change policies on a whim that can disrupt VCV's business model. This would place VCV's risk in a small number of baskets. | |||
## Why does the Audio module from Core consume so much CPU? | |||
## Why does VCV Audio consume so much CPU? | |||
The CPU meter measures the time spent processing each module, not the limited "resource" of CPU power. | |||
In order for playback timing to be consistent, your audio device, and thus the Audio module, waits until all samples in the current audio buffer are played before moving onto the next audio buffer. | |||
The CPU meter measures the time spent processing each module, not the "resource" of CPU power. | |||
In order for playback timing to be consistent, your audio device, and therefore VCV Audio, waits until all samples in the current audio buffer are played before moving onto the next audio buffer. | |||
Otherwise, your device's DAC and ADC would play and record at very inconsistent and incorrect sample rates. | |||
While waiting, the engine thread is put to sleep, so no energy is consumed by the thread. | |||
See [CPU timer](MenuBar.html#cpu-timer) for more info. | |||
## Is VCV Rack available as a VST/AU/AAX plugin for DAWs? | |||
@@ -89,4 +71,4 @@ The primary "standalone" version of Rack v2 will continue to be free/open-source | |||
Rack's window library GLFW does not support [touch input](https://github.com/glfw/glfw/issues/42), so Rack relies on the operating system to control the mouse cursor using the touch screen. | |||
This means that multi-touch gestures do not work. | |||
However, you can set `"allowCursorLock"` to `false` in the `settings.json` file in Rack's local directory to improve knob moving gestures. | |||
However, you can set `"allowCursorLock"` to `false` in `<Rack user dir>/settings.json` to improve touch cursor handling for knobs. |
@@ -2,11 +2,12 @@ | |||
## System Requirements | |||
VCV Rack is free software, so you may simply install it to check if it works. | |||
However, if you are experiencing performance issues, make sure you have the following. | |||
VCV Rack is free software, so you may simply download and run the software to see if it works. | |||
However, if you are experiencing performance issues, make sure you have at least the following hardware. | |||
- Operating system: MacOS 10.7+, Windows 7+, or Linux (Ubuntu 16.04+, etc) | |||
- CPU: Intel/AMD 64-bit processor from \~2011 or later | |||
- Graphics: Dedicated Nvidia/AMD graphics card from \~2013 or later. Integrated (non-dedicated) graphics such as Intel HD/Iris are not recommended and cause significantly increased CPU usage. | |||
- Graphics: Dedicated Nvidia/AMD graphics card from \~2013 or later. | |||
Integrated (non-dedicated) graphics such as Intel HD/Iris are not recommended and cause significantly increased CPU usage. | |||
- RAM: 1GB | |||
- Disk space: 1GB | |||
@@ -16,22 +17,16 @@ Download Rack on the [VCV Rack website](https://vcvrack.com/). | |||
### Installing on Mac | |||
Open the DMG image and copy the Rack app to your Applications folder. | |||
If you wish to use [VCV Bridge](Bridge.html), copy `VCV-Bridge.vst` to the VST folder and/or the `VCV-Bridge.component` Audio Unit to the Components folder. | |||
Download, unzip, and copy the Rack app to your Applications folder. | |||
### Installing on Windows | |||
Run the installer. | |||
If you wish to use [VCV Bridge](Bridge.html), make sure the VST feature is checked for your architecture (32- or 64-bit) and specify the location to install it in the next few steps. | |||
### Installing on Linux | |||
Unzip the zip file. | |||
If you wish to use [VCV Bridge](Bridge.html), copy the `Bridge/VCV-Bridge.so` VST plugin to your system's VST search location such as `/usr/lib/vst`. | |||
## Installing plugins | |||
On [VCVRack.com](https://vcvrack.com/) or the [VCV Plugin Manager](https://vcvrack.com/plugins.html), add each plugin you wish to install. | |||
@@ -56,7 +51,6 @@ Note: Do not download the plugin via GitHub's green "Clone or download" button. | |||
### Running on Mac | |||
Launch Rack from the Applications folder or the dock. | |||
On modern Mac versions, you may need to right click the application and click "Open" when launching for the first time. | |||
### Running on Windows | |||
@@ -69,9 +63,9 @@ Or with the command-line, `cd` into the `Rack` directory and run `./Rack`. | |||
### Command line usage | |||
To launch Rack from the command line, `cd` into Rack's directory, and run `./Rack`. | |||
- `-d`: Enables development mode | |||
- `-g <dir>`: Sets Rack's global directory | |||
- `-l <dir>`: Sets Rack's local directory | |||
- `<patch filename>`: Loads a patch file | |||
To launch Rack from the command line, `cd` into Rack's directory, and run `./Rack`, optionally with the following options. | |||
- `<patch filename>`: Loads a patch file. | |||
- `-u <dir>`: Sets Rack's system directory. | |||
- `-s <dir>`: Sets Rack's user directory. | |||
- `-d`: Enables development mode. | |||
This sets the system and user directories to the current directory, uses the terminal (stderr) for logging, and disables the Plugin Manager to prevent overwriting plugins. |
@@ -0,0 +1,94 @@ | |||
# Menu Bar | |||
 | |||
## File | |||
### New | |||
Clears the patch and loads the template patch (`<Rack user dir>/template.vcv`). | |||
### Open/Save/Save as | |||
Opens/saves the patch from/to a `.vcv` file. | |||
Patches use the [JSON](https://json.org/) format and can also be viewed with a text editor. | |||
### Save template | |||
Saves the patch as `<Rack user dir>/template.vcv` so it is loaded when creating new patches. | |||
### Revert | |||
Restores the patch from the last saved state. | |||
### Quit | |||
Autosaves the patch to `<Rack user dir>/autosave.vcv` and closes Rack. | |||
Rack also autosaves every 15 seconds to prevent losing work due to a crash, power failure, etc. | |||
## Edit | |||
### Undo/Redo | |||
Rewinds and plays back all actions that edit the patch. | |||
### Clear cables | |||
Removes all cables from the patch. | |||
## View | |||
### Parameter tooltips | |||
Enables/disables tooltips when hovering over parameters (knobs, sliders, buttons, etc) which display the name, numeric value, and optionally description of the parameter. | |||
### Lock modules | |||
Locks/unlocks modules from being moved by the mouse. | |||
Prevents accidentally dragging modules. | |||
### Zoom | |||
Adjusts the zoom level for the rack from 25-400%. | |||
Double-click to reset to 100%. | |||
### Cable opacity | |||
Sets the transparency level for patch cables. | |||
Double-click to reset to 50%. | |||
### Cable tension | |||
Sets the relative length of patch cables. | |||
Double-click to reset to 0.5. | |||
### Fullscreen | |||
Expands Rack to fill the screen with no window borders. | |||
## Engine | |||
### CPU timer | |||
Enables/disables the measurement of time for each module to generate each sample (see [Sample rate](#sample-rate)). | |||
This displays a meter on each module with the number of microseconds (ÎĽs) and the percentage of time spent in the module's assigned thread (see [Threads](#threads)). | |||
If running in single-threaded mode, the total percentage must equal 100%, with "blocking" modules like [VCV Audio](Core.html#audio) consuming the remaining time by "sleeping" until the audio device is ready for more audio. | |||
If multi-threading is enabled, the total percentage may equal up to \\(N \times 100\\%\\), although this number is a bit less in reality due to [multi-threading overhead](https://en.wikipedia.org/wiki/Amdahl%27s_law). | |||
Timing takes CPU power itself, so it is recommended to disable the CPU timer when it is not needed for best performance. | |||
### Sample rate | |||
Sets Rack's engine sample rate. | |||
Rack's engine works by repeatedly stepping the state of each module by `1 / sampleRate` seconds, producing 1 new sample for each output. | |||
A higher sample rate decreases the timestep, resulting in more accurate analog circuit modeling and digital algorithms, while a lower sample rate decreases engine CPU usage. | |||
### Threads | |||
Sets the number of cores to be used in Rack's multithreaded engine. | |||
To minimize power usage and CPU resources for other programs to use, disable multithreading by selecting 1 thread. | |||
Using more threads increases CPU usage but increases the maximum number of modules you can use in the rack. | |||
It is recommended to begin with 1 thread, and if you experience audio hiccups, try increasing the thread count by 1. | |||
Continue adding threads until no hiccups occur. | |||
The maximum recommended number of threads is the number of physical cores in your machine. | |||
For example, a quad-core machine would likely maximize the number of modules by using 4 threads. | |||
Due to [simultaneous multithreading](https://en.wikipedia.org/wiki/Simultaneous_multithreading) such as [Intel Hyper-Threading](https://en.wikipedia.org/wiki/Hyper-threading), you may attempt to use up to twice as many threads as physical cores in your machine, but typically this results in worse performance with higher power usage. | |||
## Plugins | |||
### Login | |||
Logs into your VCV account registered at [vcvrack.com](https://vcvrack.com/). | |||
Email [contact@vcvrack.com](mailto:contact@vcvrack.com) for account assistance. | |||
### Update all | |||
Updates and downloads all new plugins and plugin versions added to your VCV account. | |||
Rack must be restarted to load new plugin updates. | |||
## Help | |||
### Manual | |||
Opens [this manual](QuickStart.html). | |||
### Open user folder | |||
Opens the [Rack user directory](FAQ.html#where-is-the-rack-user-directory) in Windows Explorer, Apple Finder, etc. |
@@ -1,5 +1,7 @@ | |||
# Plugin Development Tutorial | |||
*TODO Update for v1* | |||
## Prerequisites | |||
- Familiarity with C++ is required. | |||
@@ -1,11 +1,11 @@ | |||
# Plugin Licensing | |||
VCV Rack is open-source/free software, but you should still familiarize yourself with the [VCV Rack licenses](https://github.com/VCVRack/Rack/blob/v1/LICENSE.md) before releasing your plugin, to avoid misuse of intellectual property. If in doubt, send your licensing questions to contact@vcvrack.com. | |||
VCV Rack is free/open-source software, but you should still familiarize yourself with the [VCV Rack licenses](https://github.com/VCVRack/Rack/blob/v1/LICENSE.md) before releasing your plugin, to avoid misuse of intellectual property. If in doubt, send your licensing questions to [contact@vcvrack.com](mailto:contact@vcvrack.com). | |||
### I want to release my plugin under the [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.en.html) (GPLv3). | |||
Since Rack is licensed under GPLv3, you may license your plugin under GPLv3 as well. | |||
You may do anything with your plugin that the GPLv3 allows, including selling it without a commercial license (below) as long as you release the source code under GPLv3. | |||
You may do anything with your plugin that the GPLv3 allows, including selling it without a [commercial plugin license](#i-want-to-sell-my-plugin-commercially-under-non-gplv3-terms) as long as you release your plugin's source code under GPLv3. | |||
### I want to release my plugin under a different open-source license or freeware. | |||
@@ -13,7 +13,7 @@ Rack offers a [VCV Rack Non-Commercial Plugin License Exception](https://github. | |||
You may choose: | |||
- **Open-source**. [BSD 3-clause](https://opensource.org/licenses/BSD-3-Clause), [MIT](https://opensource.org/licenses/MIT), and [CC0](https://creativecommons.org/publicdomain/zero/1.0/) are popular licenses. | |||
- **Closed-source freeware**. | |||
- **Donationware**, as long as a donation is not required for use. | |||
- **Donationware**, as long as a donation is not required for use (otherwise you need a [commercial plugin license](#i-want-to-sell-my-plugin-commercially-under-non-gplv3-terms)). | |||
Note that if you copy significant portions of Rack's code into your own plugin, you must license it under GPLv3. | |||
@@ -27,13 +27,19 @@ This license also includes permission to use the [Component Library](https://git | |||
It is recommended to contact VCV as early as possible in your development process to make sure the license agreement is ready well before you release your plugin. | |||
You can expedite the licensing processing by sending concepts and design mockups along with your license request. | |||
You may also wish to sell your plugin on the [VCV Store](https://vcvrack.com/plugins.html). | |||
Some benefits of distributing your plugin on the VCV Store: | |||
- Most Rack users are already familiar with the VCV Store checkout system. | |||
You may also wish to sell your plugin on the [VCV Plugin Manager](https://vcvrack.com/plugins.html). | |||
Some benefits of distributing your plugin on the VCV Plugin Manager: | |||
- Most Rack users are already familiar with the VCV Plugin Manager checkout system. | |||
- Plugin updates are automatically synchronized to users' computers. | |||
- VCV offers advanced technical support with the Rack SDK and DSP library. | |||
- You may supply VCV with either binary packages for Mac/Windows/Linux, or a source package which we will build for you. | |||
- Access to dashboard for managing customers' purchases and viewing real-time statistics. | |||
You must follow the **VCV Rack Plugin Ethics Guidelines** in order to obtain a commercial plugin license: | |||
- You may not clone the brand name, model name, logo, or layout of components (knobs, ports, switches, etc) of an existing hardware or software module without permission from its owner, regardless of whether these are covered under trademark/copyright law. | |||
### VCV Plugin Ethics Guidelines | |||
- You may not clone the brand name, model name, logo, panel design, or layout of components (knobs, ports, switches, etc) of an existing hardware or software product without permission from its owner, regardless of whether these are covered under trademark/copyright law. | |||
It is recommended to follow these guidelines for all plugins, but you are not legally required to do so. | |||
However, it is a requirement for: | |||
- distributing your plugin on the [VCV Plugin Manager](https://vcvrack.com/plugins.html). | |||
- obtaining a [commercial plugin license](#i-want-to-sell-my-plugin-commercially-under-non-gplv3-terms). |
@@ -1,5 +1,7 @@ | |||
# Quick Start | |||
*TODO Update for v1* | |||
Once Rack is installed and launched *(see [Installing](Installing.html))*, you will see an empty rack with a toolbar. | |||
 | |||
@@ -1,17 +0,0 @@ | |||
# Toolbar | |||
## Power meter | |||
When power meters are enabled, Rack measures the amount of time spent processing each module in **mS** (millisamples). | |||
This is a unit of time equal to \\(0.001 / \text{sample rate}\\). | |||
In many ways, this is analogous to the module power limit imposed by hardware modular synthesizers in mA (milliamperes). | |||
To maintain a stable audio clock, the total amount of time spent processing all modules must equal **1000 mS**. | |||
To achieve this, the [Audio](Core.html#audio) module from [Core](Core.html) uses your audio device's high-precision clock to regulate Rack's engine, so it idles for the remaining mS until this total is met. | |||
If the Audio idle time falls close to an average of 0 mS over its block size, an audio stutter may occur. | |||
This can be caused by other modules consuming lots of mS. | |||
## Internal sample rate | |||
Rack advances the state of each module by the duration specified by Rack's internal sample rate. | |||
A higher sample rate decreases the timestep, resulting in more accurate analog circuit modeling at the expensive of more mS consumed by all modules. |
@@ -1,33 +1,32 @@ | |||
# ABI/API Version | |||
An **ABI** (Application Binary Interface) is a machine-readable list of symbols (functions, globals, and classes) that can only be called, accessed, and used in specific ways. | |||
An **API** (Application Programming Interface) consists of C and C++ headers (`.h` and `.hpp` files) that define how the ABI can be used. | |||
An **ABI** ([Application Binary Interface](https://en.wikipedia.org/wiki/Application_binary_interface)) is a machine-readable list of symbols (functions, globals, and classes) that can only be called, accessed, and used in specific ways. | |||
An **API** ([Application Programming Interface](https://en.wikipedia.org/wiki/Application_programming_interface)) consists of C and C++ headers (`.h`/`.hpp`) that define how the ABI can be used. | |||
Rack plugins must be compiled against a particular *major version* of Rack to match its ABI, so that when Rack loads them, they link to Rack's symbols correctly. | |||
The major version is `X` in the version name `vX.Y` (or `v0.X.Y` for beta versions). | |||
The major version is `X` in the version name `vX.Y.Z`. | |||
## Symbol additions | |||
In rare cases, symbols might be added to the API/ABI of Rack in a minor version update. | |||
Plugins may use these new symbols, but note that they cannot be loaded with older versions of Rack. | |||
Symbols might be added to the API/ABI of Rack in a minor version update. | |||
Plugins may use these new symbols, but they cannot be loaded with older versions of Rack. | |||
Users will need to upgrade their Rack minor version to load your plugin. | |||
Once a symbol is added to a *minor version* update, its API/ABI is not changed. | |||
The minor version is `Y` in the version name `vX.Y` (or `v0.X.Y` for beta versions). | |||
The minor version is `Y` in the version name `vX.Y.Z`. | |||
This is similar to how VST plugins work, where for example, VST 2.3 plugins cannot load in DAWs that only implement the VST 2.2 standard, except that Rack releases versions more frequently at this time. | |||
This is similar to how VST plugins work, where for example, VST 2.3 plugins cannot load in DAWs that only implement the VST 2.2 standard. | |||
## Git branches and tags | |||
In [Rack's git repository](https://github.com/VCVRack/Rack), each major version has its own branch, labeled `v0.5`, `v0.6`, etc. | |||
In [Rack's git repository](https://github.com/VCVRack/Rack), each major version has its own branch, labeled `v1`, `v2`, etc. | |||
There is no `master` branch. | |||
The default branch on GitHub is the major version for the latest release of Rack listed at [vcvrack.com](https://vcvrack.com/). | |||
To update the major version of your source tree, simply check out its branch. | |||
It is highly recommended to run `make clean` in the root and `dep/` directories after or before switching branches. | |||
When any version of Rack is released, the build's commit is tagged with its full version name (e.g. `v0.6.0`). | |||
When any version of Rack is released, the build's commit is tagged with its full version name (e.g. `v1.0.0`). | |||
However, this is only for informative purposes. | |||
Building from "detached heads" of branches is not supported, since dependency URLs and other issues may need to be fixed after time has passed from the release date. |
@@ -62,7 +62,7 @@ If your module has polyphonic outputs, then it can be considered a "polyphonic m | |||
It is recommended to support up to 16 channels, which is the maximum that Rack allows. | |||
Typically each voice in your module can be abstracted into an "engine". | |||
The number of active engines \\(N\\) should be defined by the number of channels of the "main" input (e.g. 1V/oct input for VCOs, audio input for filters, gate input for envelope generators, etc). | |||
The number of active engines \\(N\\) should be defined by the number of channels of the "primary" input (e.g. 1V/oct input for VCOs, audio input for filters, gate input for envelope generators, etc). | |||
All other secondary inputs with \\(M\\) channels should follow these rules: | |||
- If monophonic (\\(M = 1\\)), its voltage should be copied to all engines. | |||
- If polyphonic with enough channels (\\(M \geq N\\)), each channel voltage should be used in its respective engine. | |||
@@ -10,4 +10,8 @@ body, h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend { | |||
.wy-nav-content { | |||
max-width: 1000px; | |||
} | |||
img.module-screenshot { | |||
height: 380px !important; | |||
} |
@@ -15,7 +15,7 @@ Rack | |||
QuickStart.md | |||
Installing.md | |||
FAQ.md | |||
Toolbar.md | |||
MenuBar.md | |||
Core.md | |||
.. toctree:: | |||
@@ -34,7 +34,6 @@ Rack | |||
:caption: Rack Development | |||
Building.md | |||
Contributing.md | |||
Version.md | |||
.. toctree:: | |||