Doc edits/VST3 Build fixes.

2022-08-18 22:21:57 -04:00
parent a57865f014
commit b6ea1fd72b
22 changed files with 374 additions and 240 deletions
@@ -1,26 +1,58 @@
+---
+page_icon: img/AudioLatency.jpg
+---
 ## Optimizing Audio Latency

-Note that PiPedal is not intended for use when logged in to Raspbian. Screen updates and heavy filesystem activity will cause audio dropouts. For best results, access PiPedal using the web interface remotely, through the Wi-Fi hotspot. Accessing the web interface via Wi-Fi has little or no effect on audio latency or dropouts.
+ {% include pageIcon.html %}

-With a good USB audio device, PiPedal should be able to provide stable audio with 4ms (good), or 2ms (excellent) latency on a Raspberry Pi 4 when running on a stock PREEMPT kernel. Your actual results may vary.
+This section provides information on optimizing USB audio latency on operating systems other than Raspberry Pi OS.

-The current Linux kernel provides best latency on USB audio devices when they are configured with a sampling rate of 48kHz, and 3 buffers. Cheap USB audio devices (e.g. M-Audio  M-Track Solo, available for less than $60) should be able to run without dropouts at 48kHz with 3x64 sample buffers. Most devices in this class use the same Burr-Brown chipset. Premium USB Audio devices should run stably at 48kHZ 3x32 sample buffers (about 2ms latency). I personally use the MOTU M2 USB audio adapter, which I highly recommend -- stable, quiet, low-latency, great controls, and built like a tank).
+Note that PiPedal is not intended for use when logged in interactively. Screen updates and heavy filesystem activity will cause audio dropouts. For best results, access PiPedal using the web interface remotely, through a Wi-Fi hotspot connection, Wi-Fi connection or Ethernet connection. Accessing the web interface has little or no effect on audio latency or dropouts.

-Make sure your system is fully updated, and that you are running with a kernel version of 5.10 or later, since version 5.10 of the Linux kernel provides improved support for class-compliant USB audio. The MOTU M2 (and many other USB audio adapters) will not work on versions of the kernel prior to 5.10.
+With a good USB audio device, PiPedal should be able to provide stable audio with sub-4ms latency on a Raspberry Pi 4 when running on a stock PREEMPT kernel. Your actual results may vary.

-Prefer 64-bit operating systems to 32-bit operating systems. ARM processors execute 64-bit code about 40% faster than 32-bit code providing the same functionality.
+PiPedal uses ALSA audio drivers directly. Unlike Jack audio drivers, ALSA can use 44.1k or 48k audio with no significant difference in latency, and
+does not require 3 audio buffers to work efficiently.  

-RT_PREEMPT realtime kernels (when available) are preferred but not required. (As if February 2022, there aren't any good sources for latest versions of Ubuntu or Raspberry Pi OS). PiPedal provides better (but not dramatically better) latency when running on a Raspbian Realtime kernel. Stock Raspbian provides PREEMPT real-time scheduling, but does not currently have all of the realtime patches, so interrupt latency is slightly more variable on stock Raspberry Pi OS than on custom builds of Raspbian with RT_PREEMPT patches applied.
+PiPedal provides the pipedal_latency_test utility to measure actual round-trip audio latency. You must temporarily disable pipedal (`sudo systemctl stop pipedal`), and connect the left audio output of your audio device to the left audio input of your audio device with a guitar cable to use this test. 
+
+The following table shows measured round-trip audio latencies for a MOTU M2 external USB adapter running on Raspbery Pi OS with a 48 KHz sample rate. You can use these figures as a rough guideline; but actual round-trip audio latency will depend on the audio device you are using.
+
+<table align='center'>
+    <tr><td></td><td colspan=3>Buffers</td></tr>
+    <tr><td>Size</td><td>2</td><td>3</td><td>4</td></tr>
+    <tr><td>16</td><td>Fails</td><td>185/3.9ms</td><td>201/4.2ms</td></tr>
+    <tr><td>24</td><td>192/4.0ms</td><td>213/4.4ms</td><td>236/4.9ms</td></tr>
+    <tr><td>32</td><td>219/4.6ms</td><td>236/4.9ms</td><td>272/5.7ms</td></tr>
+    <tr><td>48</td><td>253/5.3ms</td><td>299/6.2ms</td><td>348/7.2ms</td></tr>
+    <tr><td>64</td><td>280/5.8ms</td><td>346/7.2ms</td><td>411/8.6ms</td></tr>
+    <tr><td>128</td><td>442/9.2ms</td><td>571/11.9ms</td><td>699/14.6ms</td></tr>
+</table>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Table 1: Delay in samples/delay in ms on MOTU M2 @ 48KHz.
+
+Make sure your system is fully updated. A kernel version greater than 5.15 is recommened, as Linux 5.15 is known to contain patches that 
+provide significant performance improvements for USB audio devices. Version 5.10 provides patches that provide broad support for 
+USB audio adapters. Kernel versions prior to 5.10 provide limited support for a limited number of mostly obsolete USB adapters.
+PiPedal will run on kernel versions less than 5.10, but may not provide robust, stable audio.
+
+Prefer 64-bit operating systems to 32-bit operating systems. ARM processors execute 64-bit audio code about 40% faster than 32-bit code providing the same functionality.
+
+RT_PREEMPT realtime kernels (when available) are preferred but not required. However, as of February 2022, there aren't any good sources for RT_PREEMPT kernels for Ubuntu or Raspberry Pi OS, and this may not change in the future. PiPedal provides better (but not dramatically better) latency when running on an RT_PREEMPT kernel. Stock Raspberry PI OS provides PREEMPT real-time scheduling, but does not currently have all of the realtime patches, so interrupt latency is slightly more variable on stock Raspberry Pi OS than on custom builds of Raspbian with RT_PREEMPT patches applied.

 The Ubuntu Studio installer will install a realtime kernel if there is one available. But -- at least for Ubuntu 21.04 -- there is no stock RT_PREEMPT kernel for ARM aarch64.

-On a Raspberry Pi 4 device, Wi-Fi, USB 2.0, USB 3.0 and SD Card access are performed over separate buses (which is not true for previous versions of Raspberry Pi). It's therefore a good idea to ensure that your USB audio device is either the only device connected to the USB 2.0 ports, or the only device connected to the UBS 3.0 ports. There's no significant advantage to using USB 3.0 over USB 2.0 for USB audio. Network traffic does not seem to adversely affect USB audio operations on Raspberry Pi 4 (which isn't true on previous versions of Raspberry Pi). Filesystem activity does affect USB audio operation on Raspberry Pi OS, even with an RT_PREEMPT kernel; but interestingly, filesystem activity has much less effect on UBS audio on Ubuntu 21.04, even on a plain PREEMPT kernel. 
+On a Raspberry Pi 4 device, Wi-Fi, USB 2.0, USB 3.0 and SD Card access are performed over separate buses (which is not true for previous versions of Raspberry Pi). It's therefore a good idea to ensure that your USB audio device is either the only device connected to the USB 2.0 ports, or the only device connected to the UBS 3.0 ports. There are theoretical advantages to USB 3.0 over USB 2.0 for USB audio; but I don't beleive there are currently any USB audio devices that take advanage of USB 3.0 features. If in doubt, use a UBS 3.0 ports; if there are problems, of if you have a high-speed drive attached to a USB 3.0 port, use a UBS 2.0 port. 

-There is some reason to believe that there are outstanding issues with the Broadcom 2711 PCI Express bus drivers on Raspberry Pi OS realtime kernels, but as of September 2021, this is still a research issue. If you are brave, there is strong anecdotal evidence that these issues arise when the Pi 4 PCI-express bus goes into and out of power-saving mode, which can be prevented by building a realtime kernel with all power-saving options disabled. But this is currently unconfirmed speculation. And building realtime kernels is well outside the scope of this document. (source: a youtube video on horrendously difficult bugs encountered while supporting RT_PREEMPT, by one of the RT_PREEMPT team members).
+Network traffic does not seem to adversely affect USB audio operations on Raspberry Pi 4 (which isn't true on previous versions of Raspberry Pi, which use a common bus for network and USB devices). Filesystem activity does affect USB audio operation on Raspberry Pi OS, even with an RT_PREEMPT kernel; but interestingly, filesystem activity has much less effect on USB audio on Ubuntu 21.04, even on a plain PREEMPT kernel. 

-For the meantime, for best results, log off from your Raspberry Pi, and use the web interface only.
+There is some reason to believe that there are outstanding issues with the Broadcom 2711 PCI Express bus drivers on Raspberry Pi OS kernels, but as of September 2021, this is still a research issue. If you are brave, there is weak anecdotal evidence that these issues arise when the Pi 4 PCI-express bus goes into and out of power-saving mode, which can be prevented by building a realtime kernel with all power-saving options disabled. But this is currently unconfirmed speculation. And building realtime kernels is well outside the scope of this document. (source: a youtube video on horrendously difficult bugs encountered while supporting RT_PREEMPT, by one of the RT_PREEMPT team members hints at this problem).

-You may also want to watch out for temperature throttling of the CPUs. PiPedal displays the current CPU temperature in the bottom-right corner of the display. The system will reduce CPU speed in order prevent damage to the system if the CPU temperature goes above 70C (perhaps above 60C). The Pi 400 already has good heat sinks, so you shouldn't run into problems when running on a Pi 400. If you run into throttling problems on a Raspberry Pi 4, you may want to buy and install a heat sink (ridiculously cheap), or install a cooling fan. As a temporary work-around, you can orient the Raspberry Pi 4 board vertically, which can provide a real and meaningful reduction in CPU temperature.
+Temperature Throttling
+----------------------
+
+You may want to watch out for temperature throttling of the CPUs. PiPedal can be configured to display the current CPU temperature in the bottom-right corner of the display. The system will reduce CPU speed in order prevent damage to the system if the CPU temperature goes above 70C (perhaps above 60C). The Pi 400 already has good heat sinks, so you shouldn't run into problems when running on a Pi 400. If you run into throttling problems on a Raspberry Pi 4, you may want to buy and install a heat sink (ridiculously cheap), or install a cooling fan (a couple of dollars). As a temporary work-around, you can orient the Raspberry Pi 4 board vertically, which can provide a real and meaningful reduction in CPU temperature.
+
+My development system has both a heat sink, and a fan. The CPU temperature rarely goes above 60C.

 --------
 [<< System Requirements](ChoosingAUsbAudioAdapter.md)  | [Up](Documentation.md) | [Command-Line Configuration of PiPedal >>](CommandLine.md)
@@ -1,12 +1,21 @@
+---
+page_icon: img/UsbAdapter.jpg
+---
+
 ## Choosing a USB Audio Adapter

-The qualitty of the audio adapter dramatically affects the quality of the guitar effects. Amp models are particularly sensitive to poor signal-to-noise ratios, because overdrive effects boost the level of noise more than the level of the actual signal. For best results, you should choose a 24-bit audio adapter that provides at least 105db (A-weighted) signal-to-noise ratio. I personally use and recommend the Motu M2 USB audio adapter, although there are plenty of other pro-quality audio adapters that will work as well. I would urge you to avoid cheaper USB audio adapters that sell for less than US$70, which will almost certainly not provide input signals of sufficient quality.
+{% include pageIcon.html %}

-Ideally, you want a USB adatper that provides an input volume knob. For best results, you want the input signal to be as high as possible without clipping. (Clipped input signals sound horrible). USB audio adapters without volume knobs usually do provide internal input volume controls, which have to be set using custom software. PiPedal does not currently allow you to set the internal trim levels of USB audio adapters. By default, these adapters will expect line level-signals. But instrument levels are about 40db quieter than line-level signals; so you will not get good results if you don't adjust the input signal trim levels of your audio adapter. 
+
+The quality of the audio adapter you use dramatically affects the quality of the guitar effects. Amp models are particularly sensitive to poor signal-to-noise ratios, because overdrive effects boost the level of noise more than the level of the actual signal. For best results, you should choose a 24-bit audio adapter that provides at least 105db (A-weighted) signal-to-noise ratio. 
+
+I personally use and recommend the Motu M2 USB audio adapter, although there are plenty of other pro-quality audio adapters that will work as well. Cheaper USB audio adapters that sell for less than US$70 will almost certainly not provide adequate signal-to-noise ratio for best results.
+
+Ideally, you want a USB adapter that provides an input volume knob, and an instrument-level input jack. For best results, you want the input signal to be as high as possible without clipping. (Clipped input signals sound horrible).

 Pay close attention to the input VU meter of the first effect in your guitar effect chain. That will indicate the signal level coming into the USB adapter. Ideally, you want the value peaking solidly in the yellow range of the VU meter, and NEVER going red.

-Again, the MOTU M2 excels in this regard. It provides large, volume knobs for input and output, along with very readable VU meters which indicate both input and output signal levels. 
+Again, the MOTU M2 excels in this regard. It provides large, volume knobs for input and output trim, along with very readable VU meters on the front  panel which indicate both input and output signal levels. 

 --------
 [<< Configuring PiPedal After Installation](Configuring.md)  | [Up](Documentation.md) | [Optimizing Audio Latency >>](AudioLatency.md)
@@ -1,7 +1,15 @@
+---
+page_icon: img/Setup.jpg
+icon_width: 320px
+icon_float: left
+---
 ## Configuring PiPedal After Installation

+
 Before using PiPedal, you will need to configure settings for the audio device that PiPedal will use.

+{% include pageIconL.html %}
+
 You will also want to configure PiPedal  to provide a Wi-Fi Direct access point (hotspot) that you can connect to using your phone. It's fine to use your home Wi-Fi network to connect to PiPedal when you're at home; but don't forget that when you take PiPedal out to a gig, you will need to ensure that the Wi-Fi Direct access point is enabled before you do. 

 PiPedal uses LV2 audio plugins. There are literally thousands of freely available high-quality LV2 plugins that are suitable for use as guitar effects.
@@ -50,7 +58,7 @@ The following table shows measured round-trip audio latencies for a MOTU M2 exte
 <table align='center'>
    <tr><td></td><td colspan=3>Buffers</td></tr>
    <tr><td>Size</td><td>2</td><td>3</td><td>4</td></tr>
-    <tr><td>16</td><td>No signal</td><td>185/3.9ms</td><td>201/4.2ms</td></tr>
+    <tr><td>16</td><td>Fails</td><td>185/3.9ms</td><td>201/4.2ms</td></tr>
    <tr><td>24</td><td>192/4.0ms</td><td>213/4.4ms</td><td>236/4.9ms</td></tr>
    <tr><td>32</td><td>219/4.6ms</td><td>236/4.9ms</td><td>272/5.7ms</td></tr>
    <tr><td>48</td><td>253/5.3ms</td><td>299/6.2ms</td><td>348/7.2ms</td></tr>
@@ -1,6 +1,14 @@
+---
+page_icon: img/Install3.jpg
+---
+
+
 ## Installing PiPedal

-### Install for Ubuntu or Raspberry Pi OS (64-bit)
+{% include pageIcon.html %}
+
+### Install for Ubuntu <br/>or Raspberry Pi OS (64-bit)
+

 Download the most recent Debian (.deb) package for your platform:

@@ -13,9 +21,11 @@ Install the package by running
  cd ~/Downloads  
  sudo dpkg --install pipedal_1.0.15_arm64.deb
 ```
-On Raspberry Pi OS, if you have a graphical desktop installed, you can also install package by double-clicking on the downloaded package in the File Manager.
+On Raspberry Pi OS, if you have a graphical desktop installed, you can also install the package by double-clicking on the downloaded package in the File Manager.


 After installing, follow the instructions in [Configuring PiPedal after Installation](Configuring.md).
+
+
 --------
 [<< System Requirements](SystemRequirements.md) | [Up](Documentation.md) | [Configuring PiPedal after Installation >>](Configuring.md)
@@ -1,5 +1,10 @@
+---
+page_icon: img/Requirements.jpg
+---
 ## System Requirements

+{% include pageIcon.html %}
+
 * A Raspberry PI 4B or 400, with at least 2GB of RAM to run (4GB recommended).
 * To build PiPedal, at least 4GB of RAM (8GB recommended).
 * An external USB Audio Adapter, or a Pi audio hat with at least one audio input, and one audio output.
@@ -15,7 +15,7 @@ Here is a brief list of particularly recommend plugin collections.
 |[Zam Plugins](https://zamaudio.com) ★★★☆☆ | sudo apt install zam-plugins   | Filtering, EQ, and mastering effects. |
 | [Calf Studio Gear](https:://calf-studio-gear.org) ★★★☆☆ | sudo apt install calf-plugins | Flanger, filters, reverb, rotary speaker &c |

-The GxPlugins pack requires a manual build; but it's worth the effort. It contains some extraordinarily beautiful amp and effect emulations, many of which are superior to plugins in the main Guitarix package.
+The GxPlugins pack requires a manual build; but it's worth the effort. A pre-built version for aarch64 can be downloaded [here](GxPlugins.md). It contains some extraordinarily beautiful amp and effect emulations, many of which are superior to plugins in the main Guitarix package.

 For a more complete (but still incomplete) list of LV2 audio plugins, see [here](https://lv2plug.in/pages/projects.html).

@@ -201,8 +201,8 @@
                + "px; left: 0px; top: 0px; opacity: 0.0;"
                + " display: flex; flex-flow: row none; justify-content: space-between;align-items: end; padding:20; opacity: 0.8;'>");
            {
-                document.writeln("<div><span style='font-size: 52px;color: #444;'>◄</span></div>");
-                document.writeln("<div><span style='font-size: 52px;color: #444;'>►</span></div>");
+                document.writeln("<div><span style='cursor: default;font-size: 52px;color: #444;'>◄</span></div>");
+                document.writeln("<div><span style='cursor: default;font-size: 52px;color: #444;'>►</span></div>");
            }

            document.writeln("</div>");
@@ -0,0 +1,8 @@
+
+<div style="max-width: 30%; width: {{page.icon_width}}; background: #FFF; z-index: -1; margin-left: 18px; float: right">
+    <img src="{{page.page_icon}}" style="width: 100%;background: #FFF; z-index: -1;
+     float: right" />
+    <div>
+        <p style="font-size: 10px; text-align: right;color: #888">Generated by DALL-E</p>
+    </div>
+</div>
@@ -0,0 +1,7 @@
+<div style="max-width: 30%; width: {{page.icon_width}}; background: #FFF; z-index: -1; margin-right: 18px; float: left">
+    <img src="{{page.page_icon}}" style="width: 100%;background: #FFF; z-index: -1;
+     float: right" />
+    <div>
+        <p style="font-size: 10px; text-align: right; color: #888">Generated by DALL-E</p>
+    </div>
+</div>