From 8a4e0f73b1275ddcf8948f8107ba733be05ac9dd Mon Sep 17 00:00:00 2001 From: Andrew Belt Date: Tue, 3 Dec 2019 18:46:09 -0500 Subject: [PATCH] Remove Bridge page. Add Issues page. Fix Sphinx version in README. --- Bridge.md | 68 ------------------------------------ Building.md | 2 +- FAQ.md | 43 +++++++---------------- Issues.md | 31 ++++++++++++++++ Manifest.md | 11 ++++-- Migrate1.md | 4 +-- PluginDevelopmentTutorial.md | 2 +- README.md | 4 +-- conf.py | 4 +++ index.rst | 7 ++-- 10 files changed, 65 insertions(+), 111 deletions(-) delete mode 100644 Bridge.md create mode 100644 Issues.md diff --git a/Bridge.md b/Bridge.md deleted file mode 100644 index 46151aa..0000000 --- a/Bridge.md +++ /dev/null @@ -1,68 +0,0 @@ -# Bridge - -***Note: VCV Bridge is deprecated and unsupported. It will be removed in Rack v2. See [Is VCV Rack available as a VST/AU/AAX plugin for DAWs?](https://vcvrack.com/manual/FAQ.html#is-vcv-rack-available-as-a-vst-au-aax-plugin-for-daws)*** - -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, so many people use Rack as a complete DAW to compose music and build patches without other software. - -However, *VCV Bridge* allows audio, MIDI, DAW transport, and DAW clocks to be transferred between Rack and your DAW through the included VST/AU instrument/effect Bridge plugins. - -The setup order between Rack and your DAW does not matter. - -## Setting up Bridge in Rack - -- Add an Audio or MIDI module to Rack from the [Core](Core.html) 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](Core.html#midi-cc) interface to convert them to 0-10 V signals in Rack. - -## Setting up Bridge in your DAW - -- Make sure the VST or AU Bridge plugin is installed, and launch your DAW. See the [installation instructions](https://vcvrack.com/manual/Installing.html#installing-rack) for more information about installing the VST on your platform. -- Add the "VCV Bridge" instrument or "VCV Bridge fx" effect plugin to a track. - - The instrument plugin is easier for sending MIDI to Rack, although it also supports audio input if supported by your DAW. - - The effect plugin is easier for sending audio to Rack, although it also supports MIDI input if supported by your DAW. -- Open the plugin parameters to reveal the Bridge port setting and 16 automation parameters. - -### Ableton Live - -Add a "VCV-Bridge" plugin to a MIDI track and open the automation parameters by clicking the triangle icon next to the plugin's name. -*Bridge* will send MIDI and receive audio from Rack. - -To send audio to Rack, select the Bridge's track under the "Audio To" menu on another track, and optionally select the channel pair (1/2, 3/4, 5/6, or 6/7). - -To record audio from Rack, create a new audio track and select the Bridge's track and optionally the channel pair under the "Audio From" menu. -Make sure "Monitor" is set to "In" on the Bridge's track to enable audio output even when it is not record-enabled. - -![Ableton Live VCV Bridge](images/BridgeLive.png) - -### Cubase -TODO - -### FL Studio -In FL Studio Add a "VCV-Bridge" Channel. Inside Channel settings, navigate to Processing tab and check "Make bridged" and "Use fixed size buffers" (this is to be fixed sooner or later). For each output in VCV you will need separate Channel listening to separate port, as there's no option to handle many Wrapper inputs in FL Studio. -VCV needs to be started *after* adding initial bridge in FL Studio, otherwise you won't hear any sound nor send any notes. -To send notes - in VCV - add MIDI-1 mapped to respective Port inside Channel in FL Studio. -To receive sound - in VCV - add SOUND, mapped to respective Port, Inputs 1-2 will send stereo sound to Wrapper in FL Studio. - -Rendering notice: It was noticed, that it is impossible to render with ASIO (Presonus AudioBox ASIO) enabled, as it renders with tons of overloads and spikes. It is advised to try rendering with default audio driver with maximal possible latency. - -### Propellerhead Reason -TODO - -### REAPER -Right-click in the REAPER Track Control Panel (underneath the main toolbar, to the left of the Arrange area). Select "Insert virtual instrument on new track...". Locate "VCV Bridge" in your VST or VSTi folders. Select the 32- or 64-bit version of VCV Bridge per your own preferences and REAPER flavor. (If desired, you can also insert the VCV Bridge into an existing track by clicking the FX button for the track.) - -When REAPER brings up the "Build Routing Confirmation" dialog, click "No" if you just want the bridge to make a typical set of stereo outputs available to REAPER, and "Yes" if you want to create eight discrete mono audio channels. REAPER will create eight additional audio tracks labeled "Output 1-8" if you select "Yes" at this dialog. Otherwise, it will only create a single track for MIDI and audio. - -(You can also manually create additional tracks / channels, and route the audio from the track containing the bridge insert into these additional tracks. This enables simultaneous live capture of VCV inbound MIDI and outbound audio on separate REAPER tracks.) - -The bridge insert defaults to port 1 in REAPER. Make sure your MIDI and audio modules in Rack are all set to communicate with Bridge, and that the port settings in those Rack modules also match the intended port number from your REAPER bridge track or channel. - -You should now be able to play Rack via your MIDI controller from the armed bridge channel in REAPER. REAPER auto-maps and -arms the track for MIDI input, and also enables record monitoring, when the track is created with "Insert virtual instrument on new track." If you added VCV Bridge to your REAPER project another way, you may need to arm the track and turn record monitoring on. - -To record audio from Rack, right-click on the record arm button for the track that you want to capture Rack's output audio from the bridge, and select "Record: output" --> "Record: (whatever_audio_format_is_desired)". - -*Note:* If REAPER is already open with a VCV bridge instance created, and VCV is opened second with a patch that already contains MIDI and/or audio modules set to anything other than Bridge send/receive, VCV Rack may crash on startup or patch load, even if the VCV Bridge insert is currently bypassed in REAPER. You may need to close REAPER and specifically select Bridge mode in your Rack audio / MIDI setup first before attempting to bridge. diff --git a/Building.md b/Building.md index 6cf276e..b196754 100644 --- a/Building.md +++ b/Building.md @@ -73,7 +73,7 @@ Complete the [Setting up your development environment](#setting-up-your-developm Plugins can be built in two ways: - [Build Rack from source](#building-rack) and build plugins in the `plugins/` folder. (Recommended for advanced developers.) -- Download an [official Rack build](https://vcvrack.com/Rack.html) and [Rack-SDK-1.1.4.zip](https://vcvrack.com/downloads/Rack-SDK-1.1.4.zip), and build plugins anywhere you like. (Easiest/fastest.) +- Download an [official Rack build](https://vcvrack.com/Rack.html) and [the latest Rack SDK](https://vcvrack.com/downloads/), and build plugins anywhere you like. (Easiest/fastest.) Download or clone the plugin source code, e.g. diff --git a/FAQ.md b/FAQ.md index 8c957ef..c5be1e1 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,22 +1,5 @@ # FAQ -## I found a bug. - -All bug reports must be reproducible, otherwise they cannot be tested and fixed in a future release of Rack. - -Search [Rack's issue tracker](https://github.com/VCVRack/Rack/issues?q=is%3Aissue) to check if someone else has posted a similar bug report. -If you believe the problem has never been reported before, [create a GitHub account](https://github.com/) (it's free) and [open a bug report issue](https://github.com/VCVRack/Rack/issues/new?template=bug_report.md). -You must fill out the issue template, or it will be closed. - -## I have a feature request. - -All features added to Rack must begin with a well-written proposal. -If approved, it is implemented, publicly tested with development builds, and released in a future Rack version. - -Search [Rack's issue tracker](https://github.com/VCVRack/Rack/issues?q=is%3Aissue) to check if someone else has posted a similar feature request. -If you believe the feature has never been requested before, [create a GitHub account](https://github.com/) (it's free) and [open an feature request issue](https://github.com/VCVRack/Rack/issues/new?template=feature_request.md). -You must fill out the issue template, or it will be closed. - ## Where is the "Rack user folder"? The Rack user folder stores data readable/writable by Rack. @@ -43,27 +26,25 @@ 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 a large risk upon VCV. -## Why does VCV Audio consume so much CPU? - -The CPU timer measures the average *time* spent processing each sample, not the CPU *energy consumption* of modules. -Since audio devices need to play audio at real-time (rather than as fast as the Rack engine can run), the VCV Audio modules need to wait for the last audio buffer to finish playing before sending a new audio buffer. -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? -VCV Rack is a standalone application, not a DAW plugin, since Rack can be fully considered a DAW itself. -However, due to user demand, Rack will be available as a 64-bit VST2 plugin for around $99 shortly after Rack v2 is released around Dec 2019. +VCV Rack can be fully considered a DAW itself rather than a "synthesizer plugin", so Rack is a standalone application. +However, due to overwhelming user demand, a new product called *VCV Rack for DAWs* will be available as a 64-bit VST2 plugin for around $99 shortly after Rack v2 is released around Jan-Feb 2020. VST3/AU/AAX/LV2 versions might be released afterwards, but this is not yet confirmed. 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. -*VCV Bridge* was a VST2/AU plugin for bridging the standalone version of Rack with a DAW. -However, inter-process communication of audio buffers does not meet the reliability requirements of VCV and its users, so it is no longer distributed as of Rack v1. -The audio/MIDI Bridge drivers will be removed in Rack v2. +## 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. +It relied on [inter-process communication (IPC)](https://en.wikipedia.org/wiki/Inter-process_communication) between Rack (server) and the DAW plugin (client), similar to [ReWire](https://en.wikipedia.org/wiki/ReWire_(software_protocol)). +Because real-time IPC of audio cannot be achieved on non-[real-time operating systems](https://en.wikipedia.org/wiki/Real-time_operating_system), it was never intended as more than a fun experiment, and the project was concluded a month after development started. +One could say the experiment "failed", but its purpose was primarily to see how much it would fail. +VCV Bridge was deprecated in July 2018 and is now unsupported. +The Bridge VST2/AU plugin was removed in Rack 1.0 (although it can be found in [earlier Rack packages](https://vcvrack.com/downloads/)), and the Bridge audio/MIDI driver will be removed in Rack 2.0. ## Does VCV Rack work with touch screens? -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. +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 set `"allowCursorLock"` to `false` in `/settings.json` to improve touch cursor handling for knobs. +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. diff --git a/Issues.md b/Issues.md new file mode 100644 index 0000000..50860bb --- /dev/null +++ b/Issues.md @@ -0,0 +1,31 @@ +# Bugs and Features + +## 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. + +- 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. + +If you provide enough information for a developer to reproduce and identify the bug, a fix is then 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. + +- 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. + +If your proposal is approved (or modified until approved), the feature is then implemented, publicly tested with development builds, and released in a future Rack version. + +## Bug reports and feature requests for Rack plugins + +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). +- 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. diff --git a/Manifest.md b/Manifest.md index e515557..86e243a 100644 --- a/Manifest.md +++ b/Manifest.md @@ -47,7 +47,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, the identifier from the [SPDX License List](https://spdx.org/licenses/) should be used. +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. ## `.brand` @@ -85,7 +85,7 @@ Homepage for the plugin itself. *String. Optional.* -The manual of your plugin. +The manual website of your plugin. E.g. HTML, PDF, GitHub readme, GitHub wiki. ## `.sourceUrl` @@ -128,3 +128,10 @@ All tags must match the [list of allowed tags](https://github.com/VCVRack/Rack/b A one-line summary of the module's purpose. Displayed in the Module Browser tooltip. + +## `modules[].manualUrl` + +*String. Optional.* + +The manual website of the module. +If omitted, the plugin's manual is used. diff --git a/Migrate1.md b/Migrate1.md index 8d9f390..859f214 100644 --- a/Migrate1.md +++ b/Migrate1.md @@ -153,8 +153,8 @@ Once your plugin can be compiled, change `#include ` back to `#includ Add new arguments to the `Module::step()` (now called `process()`) and `Widget::draw()` methods. ```bash -perl -i -pe 's/void (\w+::)?step\(\)/void $1process(const ProcessArgs &args)/g' src/* -perl -i -pe 's/void draw\(NVGcontext \*vg\)/void draw(const DrawArgs &args)/g' src/* +perl -i -pe 's/void (\w+::)?step\(\)/void $1process(const ProcessArgs& args)/g' src/* +perl -i -pe 's/void draw\(NVGcontext \*vg\)/void draw(const DrawArgs& args)/g' src/* perl -i -pe 's/\bvg\b/args.vg/g' src/* ``` Note: `Widget::step()` has not been renamed, but this replacement will incorrectly rename it. diff --git a/PluginDevelopmentTutorial.md b/PluginDevelopmentTutorial.md index 2a7dc4c..20b0229 100644 --- a/PluginDevelopmentTutorial.md +++ b/PluginDevelopmentTutorial.md @@ -8,7 +8,7 @@ - Download and install [VCV Rack](https://vcvrack.com/Rack.html). - Follow the steps to [set up your build environment](Building.html#setting-up-your-development-environment) for your operating system. You do not need to build Rack from source if using the Rack SDK. -- Download and extract [Rack-SDK-1.1.4.zip](https://vcvrack.com/downloads/Rack-SDK-1.1.4.zip). +- [Download the latest Rack SDK](https://vcvrack.com/downloads/) and extract. This contains the Rack API headers and build system for compiling your plugin. ## Creating the template plugin diff --git a/README.md b/README.md index 5e3fcf6..5e24175 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,9 @@ Your PR will be accepted if it is a net positive benefit to readers. ## Building -Install [Sphinx](http://www.sphinx-doc.org/en/stable/) 0.8.1. Newer versions do not generate formulas and image tags properly. +Install [Sphinx](http://www.sphinx-doc.org/en/stable/) 1.8.1. Newer versions do not generate formulas and image tags properly. - pip install sphinx==0.8.1 + pip install sphinx==1.8.1 Install [recommonmark](https://github.com/rtfd/recommonmark) 0.4.0. diff --git a/conf.py b/conf.py index 624298a..16df7b2 100644 --- a/conf.py +++ b/conf.py @@ -10,6 +10,7 @@ extensions = [ ] from recommonmark.parser import CommonMarkParser +from recommonmark.transform import AutoStructify source_parsers = { '.md': CommonMarkParser, @@ -95,6 +96,9 @@ epub_exclude_files = ['search.html'] def setup(app): app.add_stylesheet("overrides.css") app.add_config_value('recommonmark_config', { + 'enable_auto_toc_tree': True, + 'auto_toc_tree_section': "Table of Contents", 'enable_math': True, 'enable_inline_math': True, }, True) + app.add_transform(AutoStructify) diff --git a/index.rst b/index.rst index 293745d..0a174eb 100644 --- a/index.rst +++ b/index.rst @@ -2,15 +2,13 @@ VCV Rack Manual =========================================== -VCV Rack is an open-source virtual modular synthesizer. +`VCV Rack `_ is an open-source virtual modular synthesizer. Edit this manual at https://github.com/VCVRack/manual. -Rack ----- - .. toctree:: :maxdepth: 1 + :caption: Rack QuickStart.md Installing.md @@ -41,5 +39,6 @@ Rack :maxdepth: 1 :caption: Appendix + Issues.md Communities.md About.md