Add Polyphony article. Add performance section to FAQ. Lots of language tweaks.

Building.md

@@ -43,7 +43,7 @@ pacman -S git wget gcc gdb make cmake tar unzip zip curl jq python
 
 *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.*
+*If the build fails for you, please [report the issue](Issues.html) to help the portability of Rack.*
 
 Clone this repository with `git clone https://github.com/VCVRack/Rack.git` and `cd Rack`.
 Make sure there are no spaces in your absolute path, since this breaks the Makefile-based build system.

Core.md

@@ -1,4 +1,4 @@
-# Core
+# Core Modules
 
 The *Core* plugin (built into Rack itself) includes utilities and interfaces for interfacing between the virtual and hardware world.
 

FAQ.md

@@ -34,6 +34,8 @@ VST3/AU/AAX/LV2 versions might be released afterwards, but this is not yet confi
 All Rack v2 plugins will be compatible with the plugin version of Rack.
 The standalone version of Rack v2 will continue to be free/open-source.
 
+Follow the [Rack development blog](https://community.vcvrack.com/t/rack-development-blog/5864) for the most up-to-date Rack development news.
+
 ## What was VCV Bridge?
 
 [VCV Bridge](https://github.com/VCVRack/Bridge) was an experimental project for transferring audio/MIDI between VCV Rack and another DAW via a VST2/AU plugin.
@@ -49,3 +51,66 @@ The Bridge VST2/AU plugin was removed in Rack 1.0 (although it can be found in [
 Rack's window library GLFW does not support [touch input](https://github.com/glfw/glfw/issues/42) yet, 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 disable "View > Lock cursor while dragging" in the menu bar to prevent Rack from grabbing the mouse cursor when interacting with knobs.
+
+## How do I improve performance of VCV Rack?
+
+VCV Rack simulates a modular synthesizer where each module itself can be a challenge to simulate on a modern computer, whether it's a virtual analog model with hundreds of analog components to simulate, or a digital module designed to be run on an ARM microprocessor similar to your smart phone's.
+A common patch of a hundred modules can require billions of floating point calculations per second to simulate and millions of 2D path elements to draw using OpenGL.
+Therefore, sometimes the following undesirable symptoms can occur when using Rack.
+
+- audio **hiccups**: Sparse and random millisecond-long audio delays. Caused by sporadically missing the audio block deadline, due to thread switching due to high CPU of other threads/processes/applications, disk activity, uncommon high-CPU branches in the DSP code, etc. during audio block processing. Depending on the audio driver and device, either zeros or the last generated sample value is inserted until the audio block is ready.
+- audio **stuttering**: Consistent audio delays every audio buffer block. Caused by the minimum CPU time required to process an audio block being greater than the real-time duration of the audio block.
+- high **power usage**: Causes laptops to drain their battery faster than during idle or typical use. More power is used by CPUs and GPUs when they are idling less often (on the microsecond scale) and operating at higher clock frequencies (managed by the OS or BIOS based on average resource load).
+- high CPU/GPU/case **temperature**: Causes the fan regulator to increase fan speeds. Heat is directly proportional to power usage.
+
+If any of these symptoms occur, you can attempt to treat them using the following tips.
+Note that some tips have trade-offs or might not provide any benefit for your situation.
+
+- Rack DSP:
+	- Use Rack's [CPU meter](MenuBar.html#cpu-meter) to identify high-CPU modules that you could remove or replace.
+	- Turn off the CPU meter when you don't need it.
+	Measuring the CPU time of each module in your patch consumes significant CPU.
+	- Increase [VCV Audio](Core.html#audio)'s block size to the highest tolerable number.
+	This results in proportionally higher audio latency but proportionally decreases block processing overhead and allows higher jitter in sample processing CPU times.
+	- Use the lowest tolerable Engine [sample rate](MenuBar.html#sample-rate).
+	Engine CPU usage is almost exactly proportional to its sample rate.
+	- Disable modules in your patch that you aren't currently using by right-clicking on their panels and choosing Disable.
+
+- Rack multi-threading:
+	- To maximize the number of modules in your patch without audio stuttering, increase the number of Rack engine threads until no stuttering occurs.
+	See [Threads](MenuBar.html#threads).
+	- To reduce power usage and temperature, use the smallest number of Rack engine threads that does not cause audio stuttering.
+
+- Graphics:
+	- Decrease Rack's frame rate to the smallest tolerable value. See [Frame rate](MenuBar.html#frame-rate).
+	- Use a dedicated (discrete) graphics card, such as Nvidia or AMD.
+	Rack is not designed for integrated graphics such as Intel HD/Iris. See [System Requirements](Installing.html#system-requirements).
+	- Make sure your graphics drivers are up-to-date.
+	- If using an Apple Retina display on your Mac, set the Rack app to use [Low Resolution Mode](https://www.maketecheasier.com/launch-apps-low-resolution-mac/).
+	- Use Rack in [fullscreen](MenuBar.html#fullscreen) mode so the graphics card does not need to render the OS user interface and other applications.
+
+- Audio hardware:
+	- Use a dedicated audio interface rather than your motherboard's audio hardware.
+	This slightly decreases the CPU overhead of sending/receiving audio buffers.
+	- Avoid using the DirectSound driver on Windows.
+	Instead use ASIO or WASAPI.
+	If you do not have an audio interface with an ASIO or WASAPI, install the freeware software [ASIO4ALL](https://www.asio4all.org/).
+	This installs an ASIO driver that communicates directly with [WDM](https://en.wikipedia.org/wiki/Windows_Driver_Model) audio interface drivers, bypassing [MME](https://en.wikipedia.org/wiki/Windows_legacy_audio_components#Multimedia_Extensions_(MME)) and [DirectSound](https://en.wikipedia.org/wiki/DirectSound).
+
+- Operating system configuration:
+	- Avoid running unnecessary programs while Rack is running.
+	- Configure your CPU to run in maximum performance mode (not energy-saving mode).
+	On Windows, see [How to enable the High performance power plan by Ableton](https://help.ableton.com/hc/en-us/articles/115000211304-How-to-enable-the-High-performance-power-plan-Windows-).
+	Mac automatically adjusts your CPU performance when applications require high CPU.
+	- If you are able, plug in your laptop.
+	Operating systems reduce CPU performance and power consumption while running on battery.
+
+- Audio/video recording:
+	- Use [VCV Recorder](https://library.vcvrack.com/VCV-Recorder/Recorder) to record audio or video.
+	Unlike non-Rack-specific screen recording software, it operates in Rack engine "time", not real-time, and therefore does not record real-time audio hiccups/stuttering.
+	This means that any hiccups/stuttering you hear in real-time will not be present when the recording is played back.
+
+- Computer hardware:
+	- Although Rack's [System Requirements](Installing.html#system-requirements) suggest that computers as old as 2013 can run Rack, it is recommended to use a computer from 2016 or later that is designed for gaming.
+	There are many gaming laptop and desktop computers on the market for as low as $300, the price of an average hardware Eurorack module.
+	Unfortunately, Apple's MacBook Air and older MacBook Pro models are not designed for gaming (despite their high price!) and are therefore not recommended for VCV Rack.

Installing.md

@@ -3,8 +3,9 @@
 ## System Requirements
 
 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)
+However, if Rack does not run or you are experiencing performance issues, make sure you have at least the following hardware.
+(Also see [How do I improve performance of VCV Rack?](FAQ.html#how-do-i-improve-performance-of-vcv-rack))
+- Operating system: MacOS 10.7+, Windows 7+, or Linux (such as Ubuntu 16.04+)
 - CPU: Intel/AMD 64-bit processor from \~2011 or later
 - Graphics: Dedicated graphics card from \~2013 or later with the latest driver software update:
 	- [Nvidia drivers](https://www.nvidia.com/Download/index.aspx)
@@ -31,23 +32,27 @@ Unzip the zip file.
 
 ## 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.
-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.
+Plugins extend VCV Rack's functionality by adding one or more modules to use in your patch.
+Plugins are typically installed via the [VCV Library](https://library.vcvrack.com/).
+See the *VCV Library Instructions* section at the bottom of the VCV Library page.
 
-If your computer is offline, you may download plugins using another computer and transfer the `Rack/plugins` folder to the offline computer.
-Downloading plugins directly from the Plugin Manager website is not supported at this time.
+If your computer is offline, you may download plugins using another computer and transfer `<Rack user folder>/plugins-v*` (See [Where is the “Rack user folder”?](FAQ.html#where-is-the-rack-user-folder)) to the offline computer.
+Downloading plugins directly from the VCV Library is not supported at this time.
 
-## Installing plugins not available on the Plugin Manager
+## Installing plugins not available on the VCV Library
 
 *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 user folder>/plugins-v1` (See [Where is the "Rack user folder"?](FAQ.html#where-is-the-rack-user-folder)). Rack will extract and load the plugin upon launch.
+Plugins for Rack are distributed as ZIP files with the format `<plugin slug>-<version>-<arch>.zip`, e.g. `MyPlugin-1.0.0-mac.zip`.
+Download the plugin ZIP package from the vendor's website to `<Rack user folder>/plugins-v*` (See [Where is the "Rack user folder"?](FAQ.html#where-is-the-rack-user-folder)).
+Do not extract the ZIP package yourself.
+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.
+Note: Plugins must be built (compiled) before Rack can load them.
+GitHub hosts plugin source code, not plugin binaries, so GitHub's green "Clone or download" button will *not* give you a plugin binary.
+However, some plugin maintainer make plugin builds available in the "Releases" section of their GitHub repository.
 
-Note: The "major" version number (e.g the `1` in `v1.2.3`) must match the major version number of Rack. See [ABI/API Version](Version.html).
+Note: The "major" version number (e.g. the `1` in `v1.2.3`) must match the major version number of Rack. See [ABI/API Version](Version.html).
 
 
 ## Running Rack
@@ -69,7 +74,10 @@ Or with the command-line, `cd` into the `Rack` folder and run `./Rack`.
 
 To launch Rack from the command line, `cd` into Rack's folder, and run `./Rack`, optionally with the following options.
 - `<patch filename>`: Loads a patch file.
-- `-s <dir>`: Sets Rack's system folder.
-- `-u <dir>`: Sets Rack's user folder.
+- `-s <Rack system folder>`: Sets Rack's system folder, containing read-only program resources. Defaults to
+	- MacOS: `<app bundle path>/Contents/Resources`
+	- Windows: install location, such as `C:\Program Files\VCV\Rack`
+	- Linux: current working directory
+- `-u <Rack user folder>`: Sets Rack's user folder, containing user settings, plugins, and patches. See [Where is the “Rack user folder”?](FAQ#where-is-the-rack-user-folder) for the default location.
 - `-d`: Enables development mode.
-This sets the system and user folders to the current working directory, uses the terminal (stderr) for logging, and disables the Plugin Manager to prevent overwriting plugins.
+This sets the system and user folders to the current working directory, uses the terminal (stderr) for logging, and disables Rack's Library menu to prevent overwriting plugins.

Issues.md

@@ -2,24 +2,26 @@
 
 ## Bug reports for Rack
 
-If you encounter a bug in Rack itself (not a plugin), such as a UI issue, broken functionality, hang, or crash, follow these steps.
+If you encounter a bug in VCV Rack (not a plugin), such as a UI issue, broken functionality, hang, or crash, follow these steps.
 
 - Log in or register for a free [GitHub account](https://github.com/).
 - Search [Rack's issue tracker](https://github.com/VCVRack/Rack/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc) to check if someone else has posted a similar bug report.
 	- If the bug is already reported, vote for it by adding a "thumb-up" reaction on the first post.
-	- If not, [open a bug report issue](https://github.com/VCVRack/Rack/issues/new?template=bug_report.md) and fill out the issue template ([found here](https://raw.githubusercontent.com/VCVRack/Rack/v1/.github/ISSUE_TEMPLATE/bug_report.md) if it doesn't appear when creating your issue).
+	- If not, [open a bug report issue](https://github.com/VCVRack/Rack/issues/new?template=bug_report.md) and fill out the issue template.
+	If the template is not filled out, your issue will be closed.
 
 A developer then attempts to reproduce and identify your bug.
 If successful, a fix is implemented, publicly tested with development builds, and released in a future Rack version.
 
 ## Feature requests for Rack
 
-If you want to propose a feature or change for Rack, follow these steps.
+If you want to propose a feature or change for VCV Rack (not a plugin), follow these steps.
 
 - Log in or register for a free [GitHub account](https://github.com/).
 - Search [Rack's issue tracker](https://github.com/VCVRack/Rack/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc) to check if someone else has posted a similar feature request.
 	- If the feature is already requested, vote for it by adding a "thumb-up" reaction on the first post.
-	- If not, [open an feature request issue](https://github.com/VCVRack/Rack/issues/new?template=feature_request.md) and fill out the issue template ([found here](https://raw.githubusercontent.com/VCVRack/Rack/v1/.github/ISSUE_TEMPLATE/feature_request.md) if it doesn't appear when creating your issue).
+	- If not, [open an feature request issue](https://github.com/VCVRack/Rack/issues/new?template=feature_request.md) and fill out the issue template.
+	If the template is not filled out, your issue will be closed.
 
 Your proposal is then discussed and possibly modified.
 If approved, the feature is implemented, publicly tested with development builds, and released in a future Rack version.
@@ -28,6 +30,6 @@ If approved, the feature is implemented, publicly tested with development builds
 
 If a bug or feature request involves a particular plugin for Rack rather than Rack itself, follow these steps.
 
-- Search for the plugin on the [VCV Library](https://vcvrack.com/plugins.html).
+- Search for the plugin on the [VCV Library](https://library.vcvrack.com/).
 - If the plugin's source code is hosted on GitHub, open an issue.
 - If not, use the provided contact information by clicking on the email icon or author's website.

Manifest.md

@@ -43,7 +43,7 @@ If you publish the source code in a git repository, it is recommended to add a g
 The license of your plugin.
 Use `"proprietary"` for commercial and freeware plugins.
 
-If your plugin uses a common open-source license, use the identifier string from the [SPDX License List](https://spdx.org/licenses/), such as `GPL-3.0-only`, `GPL-3.0-or-later`, `MIT`, `BSD-3-Clause`, `CC0-1.0`, etc.
+If your plugin uses a common open-source license, use the identifier string from the [SPDX License List](https://spdx.org/licenses/), such as `GPL-3.0-or-later`, `GPL-3.0-only`, `MIT`, `BSD-3-Clause`, `CC0-1.0`, etc.
 
 ## `.brand`
 *String. Optional.*
@@ -96,6 +96,11 @@ For GitHub URLs, use the main project page, not the `.git` URL.
 Link to donation page for users who wish to donate.
 E.g. [PayPal.Me](https://www.paypal.me/), [Cash App](https://cash.app/) links.
 
+## `.changelogUrl`
+*String. Optional.*
+
+Link to the changelog of the plugin.
+
 ## `.modules[].slug`
 *String. Required.*
 
@@ -310,3 +315,11 @@ If omitted, the plugin's manual is used.
 
 If this module has the [Hardware clone](Manifest#hardware-clone) tag, this is the URL to the [ModularGrid](https://www.modulargrid.net/) page for that module.
 Example: `"https://www.modulargrid.net/e/mutable-instruments-clouds"`
+
+## `.modules[].deprecated`
+*Boolean. Optional.*
+
+Specifies that the module should no longer be used and only remains for patch compatibility.
+If a successor module exists, add its name to the [description](Manifest#modules-description), e.g. "Replaced by MyModule 2".
+
+In a future version of Rack, deprecated modules will not be displayed in the Module Browser by default but can still be used by opening old patches.

MenuBar.md

@@ -42,6 +42,10 @@ Double-click to reset to 50%.
 ### Cable tension
 Sets the relative length of patch cables.
 Double-click to reset to 0.5.
+### Frame rate
+Sets Rack's screen refresh frequency.
+Rack re-draws its screen every [monitor v-sync](https://en.wikipedia.org/wiki/Refresh_rate), or once every $N$ v-syncs determined by this setting.
+Decreasing the frame rate results in almost exactly proportionally decreased GPU resources consumed by Rack, at the cost of more choppy motion.
 ### Fullscreen
 Expands Rack to fill the screen with no window borders.
 
@@ -51,13 +55,14 @@ Expands Rack to fill the screen with no window borders.
 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)).
 
-The CPU meter consumes engine time itself, so it is recommended to disable it when it is not needed for best performance.
+The CPU meter consumes engine CPU time itself, so it is recommended to disable it 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.
+Engine CPU usage is almost exactly proportional to its sample rate.
 
 ### Threads
 Sets the number of cores to be used in Rack's multithreaded engine.

Migrate2.md

@@ -7,4 +7,7 @@ perl -i -pe 's/(\w+)_INPUT\b/INPUT_$1/g' src/*
 perl -i -pe 's/(\w+)_OUTPUT\b/OUTPUT_$1/g' src/*
 perl -i -pe 's/(\w+)_LIGHT\b/LIGHT_$1/g' src/*
 ```
-perl -i -pe 's/app::ABI/ABI/g' src/**/* include/**/*
+perl -i -pe 's/app::ABI/ABI/g' src/**/* include/**/*
+
+
+perl -i -pe 's/AudibleInstruments\.hpp/plugin.hpp/g' src/*

PluginDevelopmentTutorial.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-- Familiarity with C++, although creating Rack plugins is a great way to learn programming and C++.
+- Familiarity with C++, although creating Rack plugins is a great way to learn programming and C++. Rack plugins are written in [C++11](https://en.cppreference.com/w/cpp/11).
 - Familiarity with navigating the command line (`cd`, `ls`, etc).
 - Familiarity with modular synthesizers. [Digital signal processing (DSP)](DSP.html) knowledge is only required if creating sound generators and processors.
 - Download and install [VCV Rack](https://vcvrack.com/Rack.html).
@@ -11,6 +11,13 @@ You do not need to build Rack from source if using the Rack SDK.
 - [Download the latest Rack SDK](https://vcvrack.com/downloads/) and extract.
 This contains the Rack API headers and build system for compiling your plugin.
 
+In your terminal, run
+```bash
+export RACK_DIR=<Rack SDK folder>
+```
+to specify the absolute path of the extracted Rack SDK.
+You may wish to add this line to your `~/.bashrc` or other shell environment, so you don't have to define it every time you open a terminal.
+
 ## Creating the template plugin
 
 The `helper.py` script included in the Rack SDK is an easy way to create a plugin template.
@@ -20,7 +27,7 @@ Decide on a [slug](Manifest.html#slug) for your plugin.
 We will use `MyPlugin` for this tutorial.
 Run
 ```bash
-<Rack SDK folder>/helper.py createplugin MyPlugin
+$RACK_DIR/helper.py createplugin MyPlugin
 ```
 to create a folder called `MyPlugin/` in your current directory.
 Example session:
@@ -42,7 +49,7 @@ Initialized empty Git repository in /home/VCV/MyPlugin/.git/
 ```
 You can change this manifest later by editing `plugin.json`. (See [Manifest](Manifest.html)).
 
-To test your build system, you may run `RACK_DIR=<Rack SDK folder> make` in the plugin directory.
+To test your build system, you may run `make` in the plugin directory.
 If it succeeds, an "empty" plugin will be built containing no modules.
 However, this is an good opportunity to check that your build environment is set up correctly.
 
@@ -118,9 +125,14 @@ Then add the following code to the `process()` function, which is called every a
 		lights[BLINK_LIGHT].setBrightness(blinkPhase < 0.5f ? 1.f : 0.f);
 	}
 ```
-Compile the plugin with `RACK_DIR=<Rack SDK folder> make`.
-If this succeeds, you can build a distributable plugin package with `RACK_DIR=<Rack SDK folder> make dist` or automatically install it to your Rack installation with `RACK_DIR=<Rack SDK folder> make install`.
-You should now be able to test your plugin by opening Rack and adding your module from the Module Browser.
+Compile your plugin with `make`.
+If the build succeeds, you can generate a distributable plugin package with `make dist`, which places it in `dist/`.
+
+You can automatically install the plugin package to your [Rack user folder](https://vcvrack.com/manual/FAQ#where-is-the-rack-user-folder) with `make install`.
+You should now be able to test your plugin by opening Rack and choosing your module in the Module Browser.
+
+If you don't see your plugin in Rack's Module Browser, check the `log.txt` file in your Rack user folder.
+This file contains warnings about plugins that fail to load and error messages if your plugin crashes.
 
 ## Beyond the tutorial
 

PluginLicensing.md

@@ -2,16 +2,21 @@
 
 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).
+## 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) free/open-source license.
 
 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 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.
+VCV recommends that supporters of free/open-source software license their Rack plugins under GPLv3+ ([SPDX license identifier](https://spdx.org/licenses/) `GPL-3.0-or-later`).
+This license gives users the [Four Essential Freedoms](https://www.gnu.org/philosophy/free-sw.html) of free software and follows [OSI's Open Source Definition](https://opensource.org/osd-annotated).
 
-Rack offers a [VCV Rack Non-Commercial Plugin License Exception](https://github.com/VCVRack/Rack/blob/v1/LICENSE.md) which allows you to license your plugin under any terms you want, as long as it is offered free of charge.
+Licensing your Rack plugin under GPLv3+ requires that derivative works are also licensed as free software under the GPLv3.
+This prevents a company from turning your source code into proprietary (non-free) software without your explicit permission.
+
+## I want to release my plugin under a different open-source license or freeware.
+
+Rack offers a [VCV Rack Non-Commercial Plugin License Exception](https://github.com/VCVRack/Rack/blob/v1/LICENSE.md) which allows you to license your plugin under any terms of your choice, as long as it is offered free of charge.
 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.
+- **Open-source**. Examples of non-GPL licenses: [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/).
 - **Closed-source freeware**.
 - **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)).
 
@@ -19,7 +24,7 @@ Note that if you copy significant portions of Rack's code into your own plugin,
 
 If someone makes a fork of your non-GPLv3 open-source plugin that is not a Rack plugin (e.g. a port to VST or a digital hardware module), their source code becomes no longer linked to VCV Rack and is thus no longer a "derived work" of Rack, so Rack's license does not apply to their source code.
 
-### I want to sell my plugin commercially under non-GPLv3 terms.
+## I want to sell my plugin commercially under non-GPLv3 terms.
 
 VCV offers commercial royalty licensing for Rack plugins by emailing [contact@vcvrack.com](mailto:contact@vcvrack.com).
 This license also includes permission to use the [Component Library](https://github.com/VCVRack/Rack/blob/v1/include/componentlibrary.hpp) graphics by [Grayscale](https://grayscale.info/), which are normally licensed for non-commercial use only.
@@ -27,7 +32,7 @@ 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 or design mockups along with your license request.
 
-You may also wish to sell your plugin on the [VCV Library](https://vcvrack.com/plugins.html).
+You may also wish to sell your plugin on the [VCV Library](https://library.vcvrack.com/).
 Some benefits of distributing your plugin on the VCV Library:
 - Most Rack users are already familiar with the VCV Library checkout system.
 - Plugin updates are automatically synchronized to users' computers.
@@ -35,11 +40,11 @@ Some benefits of distributing your plugin on the VCV 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.
 
-### VCV Plugin Ethics Guidelines
+## 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 obligated to do so.
 However, it is a requirement for:
-- distributing your plugin on the [VCV Library](https://vcvrack.com/plugins.html).
+- distributing your plugin on the [VCV Library](https://library.vcvrack.com/).
 - obtaining a [commercial plugin license](#i-want-to-sell-my-plugin-commercially-under-non-gplv3-terms).

Polyphony.md

@@ -0,0 +1,54 @@
+# Polyphony
+
+*VCV Rack* supports polyphonic cables containing up to 16 channels of voltage (audio, CV, gates, etc).
+To distinguish them from normal monophonic cables, polyphonic cables appear thicker and can contain any number of channels from 2 to 16.
+
+Without polyphonic cables, patching a polyphonic synth would be very cumbersome, with increasing difficulty the more voices you need to support.
+To allow a maximum of \\(N\\) voices to be played, you would need to create \\(N\\) identical VCOs, VCFs, VCAs, etc. with \\(N\\) sets of cables patched between them and then unity-mix their \\(N\\) outputs into a single signal.
+But with polyphonic cables, you only need to patch one set of modules and then configure a single "source" module to generate a polyphonic output.
+
+## Example
+
+In the screenshot below, [*MIDI-CV*](Core.html#midi-cv) is configured to generate 8 channels by right-clicking on its panel, choosing a number of "Polyphonic channels", and optionally choosing a "Polyphony mode" to specify how MIDI notes are assigned to polyphonic channels.
+Its V/OCT and GATE ports then become polyphonic outputs, and their signals can be sent to other polyphonic modules, carried by polyphonic cables.
+
+![Polyphonic patch](images/polyphonicpatch.png)
+
+Modules must be explicitly developed to support polyphony in order to handle polyphonic cables.
+These modules are identified with the ["Polyphonic"](https://library.vcvrack.com/?query=&brand=&tag=Polyphonic&license=) tag.
+
+Some modules generate polyphonic signals only when they are configured by the user, such as *MIDI-CV* explained above.
+Other modules generate polyphonic outputs when a polyphonic cable is patched into one of its inputs.
+In this example, *VCO-1* generates a polyphonic audio signal at its SINE output because a polyphonic pitch signal from *MIDI-CV's* V/OCT output is patched to *VCO-1's* V/OCT input.
+This means that if you are careful to only use modules with the "Polyphonic" tag in your patch, you can enable polyphony across the entire patch by configuring a single module, e.g. *MIDI-CV*.
+The rest of the modules turn polyphonic in a "chain reaction", starting from the polyphony source.
+
+Useful utility modules for understanding and using polyphony in Rack include [VCV Split](https://library.vcvrack.com/Fundamental/Split) for splitting a polyphonic signal into multiple monophonic signals, [VCV Merge](https://library.vcvrack.com/Fundamental/Merge) for merging multiple monophonic signals into a polyphonic signal, [VCV Sum](https://library.vcvrack.com/Fundamental/Sum) for unity-mixing all channels in a polyphonic signal, and [VCV Viz](https://library.vcvrack.com/Fundamental/Viz) for visualizing the individual channels in a polyphonic signal.
+Modules like [VCV Scope](https://library.vcvrack.com/Fundamental/Scope) can also be used for visualizing each channel separately.
+
+![Polyphonic VCV Scope](images/polyphonicscope.png)
+
+## Technical details
+
+In *Rack*, monophonic cables are actually just a special case of polyphonic cables, having just 1 channel.
+This means there is only one type of cable in *Rack*: polyphonic.
+
+Zero-channel cables are also possible, which make modules think the cable is unpatched.
+This can be useful if a module has a particular unpatched behavior you want to use but don't want to actually unpatch the cable.
+It is even possible for a hypothetical module to automate the number of channels of its outputs, in order to virtually patch/unpatch a cable according to a gate signal.
+(Email contact@vcvrack.com if you know or made a module that does this.)
+
+Modules that support polyphony almost always have better performance than using multiple copies of monophonic modules, often as high as 4x (25% the CPU).
+This is because polyphonic modules are usually written with [SIMD instructions](https://en.wikipedia.org/wiki/SIMD), and/or take advantage of compiler auto-vectorization, which allows your CPU to process 4 channels (with [SSE](https://en.wikipedia.org/wiki/Streaming_SIMD_Extensions)) simultaneously on the same core.
+
+## Other uses
+
+Despite their name, polyphonic cables are not limited to making polyphonic synthesizer patches.
+Other hypothetical uses include:
+- stereo encoding using 2-channel polyphonic cables
+- surround sound
+- [ambisonics](https://en.wikipedia.org/wiki/Ambisonics). 3rd-order requires exactly 16 channels, making *Rack's* polyphonic cables a perfect medium for ambisonics signals.
+- custom digital multi-channel bus protocols
+- carrying signals at higher sample rates than *Rack's* engine is running. This could allow lower-CPU video synthesis.
+- using [VCV Merge](https://library.vcvrack.com/Fundamental/Merge) and [VCV Split](https://library.vcvrack.com/Fundamental/Split) to "teleport" up to 16 monophonic signals to a different section of your patch to decrease cable clutter.
+This concept is similar to the [Doepfer A-180-9 Multicore](http://www.doepfer.de/A1809.htm) Eurorack module, which (ab)uses RJ45 (Ethernet) cables to carry analog signals.

QuickStart.md

@@ -29,4 +29,4 @@ Finally, adjust Mixer's first channel or main volume by clicking and dragging th
 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](https://vcvrack.com/plugins.html).
+When you are ready, install more plugins using the [VCV Library](https://library.vcvrack.com/).

Version.md

@@ -1,22 +1,21 @@
-# ABI/API Version
+# Versioning
 
-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.
+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 by a computer 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 by the compiler.
 
-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.Z`.
+A version string is structured as `vMAJOR.MINOR.REVISION` and roughly follows the [Semantic Versioning](https://semver.org/) standard.
 
+Rack can be considered as a library for plugins. Applying Semantic Versioning, this means:
+- A major Rack update makes incompatible plugin API and ABI changes.
+- A minor Rack update adds (but not removes or changes) symbols to the plugin API and ABI, making Rack backward compatible with plugins compiled against an older minor Rack version but not forward compatible with plugins compiled against a newer minor Rack version. Users are encouraged to update Rack before updating plugins to ensure that all plugins can be loaded.
+- A revision Rack update does not modify symbols but only changes functionality and fixes bugs in a compatible way.
 
-## Symbol additions
-
-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.
-
-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.
+Rack *plugins* can be considered as applications that link to the Rack library. This means:
+- A plugin's major version must match Rack's major version in order to be loaded by Rack. To make a plugin available for a new major Rack version, the plugin's source must be updated and recompiled against the new Rack SDK.
+- A minor plugin update means that new features or modules were added.
+- A revision plugin update means that bugs were fixed or existing behavior was tweaked.
 
+The most important point for users is that **Rack will only load plugins that match its major (`vX.*`) version.**
 
 ## Git branches and tags
 
@@ -25,7 +24,7 @@ In [Rack's git repository](https://github.com/VCVRack/Rack), each major version
 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.
+It is not recommended to checkout a branch to upgrade Rack's major version unless you know how to fully clean a git tree with submodules.
 
 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.

index.rst

@@ -10,11 +10,11 @@ Edit this manual at https://github.com/VCVRack/manual.
    :maxdepth: 1
    :caption: Rack
 
-   QuickStart.md
-   Installing.md
    FAQ.md
+   Installing.md
    MenuBar.md
    Core.md
+   Polyphony.md
 
 .. toctree::
    :maxdepth: 1