Added a page about the new Virtual MIDI Keyboard

diff --git a/include/the-window-menu.html b/include/the-window-menu.html
index f0af1e45a6aeda3148e95b9925f7d2eb4a96fa1c..6c8e4c77a1816e98a57852266b29244008317ed2 100644 (file)
--- a/include/the-window-menu.html
+++ b/include/the-window-menu.html
@@ -35,7 +35,7 @@
 
        <tr><th>&square; Keyboard Shortcuts</th><td>Opens up a <a href="@@default-keyboard-bindings">Keyboard Shortcuts window</a>, which allows for easy creation or modification of any keyboard binding</td></tr>
        
-       <tr><th>&square; Virtual Keyboard</th><td>Opens up a virtual MIDI keyboard. If a MIDI track is selected (or many), this keyboard can be used to play, record or affect the selected track(s) or automation as an hardware device would.</td></tr>
+       <tr><th>&square; Virtual Keyboard</th><td>Opens up the <a href="@@virtual-keyboard">virtual MIDI keyboard</a>. If a MIDI track is selected (or many), this keyboard can be used as an hardware device would.</td></tr>
        <tr><th>Midi Tracer</th><td>Opens the <kbd class="menu">MIDI Tracer</kbd> window, allowing to follow each and every MIDI message entering or leaving Ardour</td></tr>
        <tr><th>&square; Log</th><td>Shows the <kbd class="menu">Log</kbd> window, where Ardour lists useful information, warnings and errors</td></tr>
 </table>

diff --git a/include/virtual-keyboard.html b/include/virtual-keyboard.html
new file mode 100644 (file)
index 0000000..0c9354a
--- /dev/null
+++ b/include/virtual-keyboard.html
@@ -0,0 +1,100 @@
+
+<figure class="right">
+  <img src="/images/virtual_keyboard.png" alt="The Virtual Keyboard window">
+  <figcaption class="center">
+    The Virtual Keyboard window
+  </figcaption>
+</figure>
+
+<p>
+  The <dfn>Virtual Keyboard</dfn> is a software MIDI instrument, similar to
+  <a href="https://vmpk.sourceforge.io/">VMPK</a> that can be used like an
+  hardware musical keyboard would, to emit MIDI events.
+</p>
+
+<p>
+  It can be used to test or record MIDI notes or events, as the computer 
+  keyboard can be (and is, by default) mapped to the virtual MIDI keyboard.
+  The keyboard layout can be chosen in the 
+  <a href="@@preferences#preferences-midi">MIDI Preferences</a>.
+</p>
+
+<p>
+  The lower part of the window is a piano keyboard. The current keyboard
+  mapping is overlaid on the notes, as are the different <em>C</em> notes,
+  indicating what octaves are shown.
+</p>
+
+<p>
+  The upper part comprises (from left to right):
+</p>
+
+<ul>
+       <li>
+               A channel selector to choose on which MIDI channel the events are generated
+       </li>
+       <li>
+               A pitch bend that can bend &plusmn;2 semtones up or down. The controls are:
+               <ul>
+                       <li>Mousewheel up/down : persistent bend up/down</li>
+                       <li>Mouse-drag up/down (by <kbd class="mouse">left</kbd>-clicking
+                       anywhere in the slider) : sprung-mode bend up/down (returns to
+                       &plus;0 semitone when the mouse button is released)</li>
+                       <li><kbd>F1</kbd> : abruptly &minus;2 semitones</li>
+                       <li><kbd>F2</kbd> : abruptly &minus;1 semitone</li>
+                       <li><kbd>F3</kbd> : abruptly &plus;1 semitone</li>
+                       <li><kbd>F4</kbd> : abruptly &plus;2 semitones</li>
+                       <li><kbd>&darr;</kbd> : ramps to &minus;2 semitones</li>
+                       <li><kbd>&uarr;</kbd> : ramps to &plus;2 semitones.</li>
+               </ul>
+       </li>
+       <li>
+               A modulator, with a modulation depth between 0 and 127, 127 being
+               a modulation of &plusmn; 1 semitone, so 2 semtones peak-to-peak.
+       </li>
+       <li>
+               Four assignable knobs. By default, they are:
+               <ul>
+                       <li>CC-7 (Channel Volume)</li>
+                       <li>CC-8 (Balance)</li>
+                       <li>CC-91 (Reverb)</li>
+                       <li>CC-7 (Chorus)</li>
+               </ul>
+               These controls can be assigned as needed by clicking the button under
+               each knob and selecting a different Control Number.
+       </li>
+       <li>
+               <em>Octave</em> : a selector to choose where on the keyboard (on which
+               octave) the keyboard view is. The chosen octave will be the second one
+               displayed, i.e. if "Octave" is set to 3, the leftmost displayed octave
+               will be 2.<br>
+               The selected octave is also where the keyboard mapping is set, so
+               if the octave is set to 3, in a QWERTY setup, the leftmost (lowest) note,
+               <kbd>Z</kbd>, is mapped to C3.<br>
+               The controls are:
+               <ul>
+                       <li><kbd>&larr;</kbd> : decrease Octave by one (i.e., scroll the view to the left)</li>
+                       <li><kbd>&rarr;</kbd> : increase Octave by one (i.e., scroll the view to the right)</li>
+               </ul>
+       </li>
+       <li>
+               <em>Range</em> determines how many octaves are displayed.
+       </li>
+       <li>
+               <em>Velocity</em> sets the intensity of the note, which contributes 
+               to its audio volume, and can, depending on the virtual instrument,
+               play a role in the sample selection.<br>
+               Although the drop down menu only lists a few values, scrolling the mouse
+               over the control, as with the other selectors, allows to change its
+               value with a finer in/decrement.
+       </li>
+       <li>
+               A <em>Transpose</em> selector, that shifts the notes played by its value
+               in semitones, either up or down, effectively tuning the whole keyboard.
+       </li>
+       <li>
+               A <em>Panic</em> button, to immediately stop all MIDI sound.
+       </li>
+
+</ul>
+

diff --git a/master-doc.txt b/master-doc.txt
index 797c621af18ad63668afa07509d7a7c17bd38314..63ac901efb042cf380b59e4aa2d3c8fa87e803bc 100644 (file)
--- a/master-doc.txt
+++ b/master-doc.txt
@@ -1430,6 +1430,13 @@ uri: working-with-midi/step-entry
 part: subchapter
 ---
 
+---
+title: The Virtual MIDI Keyboard
+include: virtual-keyboard.html
+link: virtual-keyboard
+part: subchapter
+---
+
 ---
 title: MIDI Automation
 include: midi-automation.html

diff --git a/source/images/virtual_keyboard.png b/source/images/virtual_keyboard.png
new file mode 100644 (file)
index 0000000..51ad458
Binary files /dev/null and b/source/images/virtual_keyboard.png differ