[ardour-manual] / include / plugin-manager.html

<p>
  The <dfn>Plugin Manager</dfn> provides a convenient interface to various
  operations on plugins and is the primary troubleshooting tools when something
  goes wrong with plugins. It works on both plugin files and the plugins index.
</p>

<figure class=center>
<img src="/images/plugin-manager.png" alt="The Plugin Manager window" width="100%" />
<figcaption class=center>The Plugin Manager window</figcaption>
</figure>

<h2>What is a plugins index?</h2>

<p>
  For each type of a plugin (e.g. VST3 or AU) there are pre-configured paths
  where these plugins are located. Every time Ardour runs, it re-scans plugins
  in these paths and recreates an index — a kind of inventory of available
  plugins. Whenever you open the <a href="@@plugin-selector">Plugin Selector</a>
  dialog, Ardour reads the list of available plugins from that index and
  displays them for you to pick.
</p>

<p>
  Re-scanning paths is important because it's common for plugins to change on
  the disk (e.g. when you installed a newer version) or get removed (when you
  don't need a plugin anymore). Sometimes plugins get corrupted due to
  a hardware failure. Indexing them often helps identifying issues early on,
  and the Plugin Manager helps reviewing the general state of affairs with
  plugins.
</p>

<p>
  Ardour also treats LV2 plugins slightly differently and scans them on startup
  unconditionally. You can disable the scanning of VST2, VST3, and AU plugins
  entirely in the <kbd class="menu">Preferences</kbd> dialog.
</p>

<h2>Plugins info</h2>

The main part of the Plugin Manager window is the table where all plugins known
to Ardour are listed. You can use it to both view information about a plugin and 
control some of its aspects:

<table class="dl">
  <tr>
      <th>Status</th>
      <td>Ardour will displays the status of every plug-in file. See below
      for more information</td>
  </tr>
  <tr>
      <th>Ign</th>
      <td>Do not load this plugin file at all</td>
  </tr>
  <tr>
      <th>Fav</th>
      <td>Set or unset the Favorite status for a plugin</td>
  </tr>
  <tr>
      <th>Hide</th>
      <td>Load this plugin file, but do not show it in the Plugin Selector</td>
  </tr>
  <tr>
      <th>Type</th>
      <td>The name of the API this plugin has been built with:
      VST2, VST3, AU, LADSPA, LV2</td>
  </tr>
  <tr>
      <th>File/ID</th>
      <td>Displays the file name for LADSPA, VST2, and VST3, as well as
      the ID for LV2 and AU</td>
  </tr>
  <tr>
      <th>Name</th>
      <td>User-visible name of the plugin</td>
  </tr>
  <tr>
      <th>Creator</th>
      <td>Developer of team of developers who created the plugin</td>
  </tr>
  <tr>
      <th>Tags</th>
      <td>Metadata that classifies the plugin by type,
      e.g. 'instrument|synth' or 'analyser'</td>
  </tr>
</table>

<p>
  The Status field specifically has the following options: 
</p>

<table class="dl">
  <tr>
    <th>OK</th>
    <td>The plugin file has loaded without any issues and the information
    in the cache about it is up to date</td>
  </tr>
  <tr>
    <th>New</th>
    <td>The plugin file has just been discovered and successfully loaded
    for the first time</td>
  </tr>
  <tr>
    <th>Updated</th>
    <td>The plugin file changed on the disk, the plugin cache has been updated
    accordingly, the plugin file loaded successfully</td>
  </tr>
  <tr>
    <th>Concealed</th>
    <td>A VST2 plugin will be hidden from Plugin Selector, if a corresponding
    VST3 plugin exists. The same applies to LV1 (LADSPA) and LV2</td>
  </tr>
  <tr>
    <th>Error</th>
    <td>There was a problem loading the plugin file</td>
  </tr>
  <tr>
    <th>Stale</th>
    <td>A plugin changed on the disk but hasn't been re-scanned
    by Ardour yet</td>
  </tr>
  <tr>
    <th>Incompatible</th>
    <td>Scan the plugin failed. Typical reasons are 32/64-bit mismatch,
    attempt to load a .dll on Linux or a .dylib on Windows</td>
  </tr>
</table>

<p>
  The <kbd class="menu">Plugin Count</kbd> section in the sidebar provides
  basic information on available plugins: how many plugins of every supported
  type are available through Ardour in total, how many failed to load, and 
  how many are missing.
</p>

<h2>Searching</h2>

<p>
  You can search for a specific plugin or a group of plugins. Simply place the
  cursor inside the input text box in the upper left corner and type. Ardour
  will search in the index
</p>

<p>
  By default, Ardour will search through plugin names, makers, and file names.
  Additionally, you can search through Type, Tags, and Paths.
</p>

<h2>Scan actions</h2>

<p>
  This section of the sidebar contains commands that operate
  on the plugins index.
</p>

<table class="dl">
  <tr>
    <th>Discover New/Updated</th>
    <td>This will run a full scan on all known paths to plugin of all supported types</td>
  </tr>
  <tr>
    <th>Update Index Only</th>
    <td>This will check which plugins were updated without scanning them</td>
  </tr>
  <tr>
    <th>Re-scan Selected</th>
    <td>This will re-scan plugin files selected in the main part of the window</td>
  </tr>
  <tr>
    <th>Re-scan Faulty</th>
    <td>This will only re-scan plugins that previously failed to load</td>
  </tr>
  <tr>
    <th>Re-scan All</th>
    <td>This will re-scan all currently known plugins</td>
  </tr>
  <tr>
    <th>Clear Staled Scan Log</th>
    <td>This will remove all entries from the index on plugins that changed
    on the disk but haven't been re-scanned</td>
  </tr>
</table>

<h2>Preferences</h2>

<p>
  This section of the sidebar allows settings paths to VST2 and VST3 plugins,
  as well as quickly open the <kbd class="menu">Preferences</kbd> dialog
  on the <kbd class="menu">Plugins</kbd> page where you can set various options
  for scanning plugins and controlling their default behavior.
</p>