Migrate old manual to GitBook

Core.md

@@ -0,0 +1,88 @@
+# 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
+![](images/Core/Audio.m.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.
+
+*Audio* currently supports the following **drivers**.
+- Core Audio on Mac
+- WASAPI and ASIO on Windows
+- ALSA on Linux
+- [VCV Bridge](#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.
+
+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
+![](images/Core/MIDI-1.m.png)
+
+*Coming soon*
+
+### MIDI-4
+![](images/Core/MIDI-4.m.png)
+
+*Coming soon*
+
+### MIDI-CC
+![](images/Core/MIDI-CC.m.png)
+
+*Coming soon*
+
+### MIDI-Trig
+![](images/Core/MIDI-Trig.m.png)
+
+*Coming soon*
+
+### Blank
+![](images/Core/Blank.m.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 2HP.
+
+### Notes
+![](images/Core/Notes.m.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.
+
+### 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.

FAQ.md

@@ -0,0 +1,74 @@
+# 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 contact@vcvrack.com 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 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 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 contact@vcvrack.com 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](https://github.com/VCVRack/Rack/issues?q=is%3Aissue), you may open an issue or email contact@vcvrack.com 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.
+
+### <a name="rack-local-directory"></a>Where is \<Rack local directory\>?
+
+- MacOS: `Documents/Rack/`
+- Windows: `My Documents/Rack/`
+- Linux: `~/.Rack/`

Glossary.md

@@ -0,0 +1,21 @@
+# Glossary
+
+
+## Core Audio
+
+https://developer.apple.com/library/content/documentation/MusicAudio/Conceptual/CoreAudioOverview/WhatisCoreAudio/WhatisCoreAudio.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

Installing.md

@@ -0,0 +1,33 @@
+# Installing
+
+Download Rack on the [VCV Rack website](https://vcvrack.com/).
+
+### 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](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.
+
+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 local directory>?](https://vcvrack.com/manual/FAQ.html#rack-local-directory)). 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.

Introduction.md

@@ -0,0 +1,7 @@
+# VCV Rack Manual
+
+The VCV Rack manual is under active development.
+
+You can contribute at https://github.com/VCVRack/manual.
+
+[PDF download](VCV-Rack-manual.pdf)

Makefile

@@ -0,0 +1,15 @@
+
+all: build
+
+build: pdf
+	gitbook build
+
+run:
+	gitbook serve --port 8080
+
+pdf:
+	gitbook pdf . VCV-Rack-manual.pdf
+
+upload: all
+	rsync _book/ vcvrack.com:vcvrack.com/manual/ -ruvz --delete
+

PluginDevelopmentTutorial.md

@@ -0,0 +1,103 @@
+# Plugin Development Tutorial
+
+### Prerequisites
+
+- Familiarity with C++ is required.
+- Follow the [Setting up your development environment](https://github.com/VCVRack/Rack#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](Building) section of the Rack README.
+- If you would like to save time, you may skip building Rack and use the [Rack SDK](https://github.com/VCVRack/Rack/issues/258#issuecomment-376293898) instead. You can then run your plugin with an official build of Rack.
+
+### Template Plugin
+
+Clone the [VCV Template plugin](https://github.com/VCVRack/Template) 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](https://inkscape.org/en/) is recommended, but [Adobe Illustrator](https://www.adobe.com/products/illustrator.html), [Affinity Designer](https://affinity.serif.com/en-gb/designer/), [Gravit Designer](https://www.designer.io/), 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
+
+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 contact@grayscale.info 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](https://github.com/VCVRack/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](https://vcvrack.com/plugins.html), see the [VCV community repository README](https://github.com/VCVRack/community#for-plugin-developers).
+
+### 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](https://github.com/VCVRack/Rack/issues/258) to receive notifications when the Rack API changes or a discussion about a change is being held.
+
+

QuickStart.md

@@ -0,0 +1,30 @@
+# Quick Start
+
+Once Rack is installed and launched *(see [Installing](Installing.html))*, you will see an empty rack with a toolbar.
+
+![Initial patch](images/initialpatch.png)
+
+Add a module by right-clicking on an empty space on the rack, or simply press `<enter>`.
+Select the [Core](Core.html) plugin and then Audio to connect Rack to an audio output on your computer.
+
+![Module Browser](images/modulebrowser.png)
+
+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.
+
+![Audio interface patch](images/audiopatch.png)
+
+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.
+
+![First patch](images/firstpatch.png)
+
+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](https://vcvrack.com/plugins.html).

README.md

@@ -0,0 +1,22 @@
+# VCV Rack Manual
+
+The scope of the manual is the VCV Rack application. It does not include individual plugins for Rack---those should be documented and hosted by the plugin developer.
+
+### Contributions
+
+Send a pull request to this repository with your edits.
+Major changes like new pages and sections are welcome, as well as minor fixes like grammar, spelling, and reorganization.
+
+### Building
+
+Install [Node](https://nodejs.org/en/). Make sure `npm` is in your PATH.
+
+Install [gitbook](https://github.com/GitbookIO/gitbook) with
+
+	npm install gitbook-cli -g
+
+Run
+
+	make run
+
+and preview the manual at http://localhost:8080/.

TOC.md

@@ -0,0 +1,13 @@
+
+- [Quick Start](QuickStart.md)
+- [Installing](Installing.md)
+- [FAQ](FAQ.md)
+- [Core](Core.md)
+- Plugin Development
+	- [Tutorial](PluginDevelopmentTutorial.md)
+	- [Voltage Standards](VoltageStandards.md)
+	- DSP
+- Rack Development
+	- Architecture
+	- Contributing
+- [Glossary](Glossary.md)

VoltageStandards.md

@@ -0,0 +1,42 @@
+# 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](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/NaN) 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`.

book.json

@@ -0,0 +1,7 @@
+{
+	"structure": {
+		"readme": "Introduction.md",
+		"summary": "TOC.md",
+		"glossary": "Glossary.md"
+	}
+}