# Nyquist Plug-in Installer

From Audacity Development Manual

The Nyquist Plug-in Installer is itself a Nyquist plug-in that simplifies the installation of other Nyquist plug-ins. All Nyquist plug-ins are plain text files that have the filename extension '.NY'. This plug-in installer provides a file browser for selecting the plug-in '.NY' file, and then copies the file to the correct location. Once the plug-in has been installed, it may be enabled in the Plug-in Manager.

  Accessed by: Tools > Nyquist Plug-in Installer...

The Nyquist Plug-in Installer installs one or more selected plug-ins for the current user, by copying the file(s) to the appropriate plug-ins folder.

  After installation, plug-ins must be enabled in the Plug-in Manager.

## To install a Nyquist plug-in:

1. Click the 'File Browser' button and select the plug-in file.
2. Click the 'OK' button to install, or 'Cancel'.
3. Carefully review the output message.
4. Use the Plug-in Manager to enable the installed plug-in.

### Allow overwriting

This is off by default, preventing you from accidentally overwriting an existing Nyquist plug-in of the same name.

If you do wish to overwrite an existing Nyquist plug-in, change that to "Allow".

## Tips:

Windows / Linux: If you are unable to locate a plug-in that you have downloaded, this may be due to your web browser adding '.TXT' to the file name. In this case, you can change the file type filter in the file browser to show text files, or to show all files. The Nyquist Plug-in Installer is able to automatically correct the file name if '.TXT' has been erroneously added.

macOS: When downloading a Nyquist plug-in from the Internet, the web browser may add '.TXT' to the file name. Nyquist Plug-in Installer can correct this error automatically. If the filename extension is anything other than '.NY' or '.NY.TXT', then it is not a valid Nyquist plug-in and installation will fail.

.ZIP files: If the plug-in file name ends with '.ZIP', then it is an archive file. The plug-in file(s) inside the '.ZIP' files must be extracted first before they can be installed.

On successful installation: The Nyquist Plug-in Installer will display the name of the installed plug-in, and the full location of where it has been installed. Note that the installed plug-in will not be available in the Audacity menus until it has been enabled in the 'Plug-in Manager'.

## Error messages:

<file name> not found or cannot be read.
  The plug-in file selected does not exist, or is not readable. Check that you have selected the correct file.
<file name> is not a supported plug-in.
  The selected file is not a Nyquist plug-in, or is malformed. (It may be a valid plug-in, but is not fully compliant with Nyquist plug-in standards.)
<file name> is not a valid Nyquist plug-in.
  Nyquist plug-ins must have the filename extension '.NY'. This error occurs if the file does not have the correct file extension and the Nyquist Plug-in Installer is unable to correct it.
<file name> cannot be written.
  The plug-in cannot be written to the default installation location. Ensure that you are logged in with a full user account (not a 'guest' account).
<file name> is already installed.
  To avoid accidentally overwriting other plug-ins, if a plug-in with the same file name exists, the Nyquist Plug-in Installer will not overwrite it.

If you want to update an older version of the plug-in, you will need to enable the Allow overwriting option.

- If you are sure that the conflicting plug-in is a totally different plug-in that happens to have the same file name, then you could try renaming the new plug-in. In this case you must ensure that the new name retains the '.NY' filename extension.
- Manual installation is still supported. See the instructions for your operating system.

## Advanced Usage

Although currently rare, some plug-ins may include additional files in TXT, HTML or LSP formats.

- TXT / HTML files may be used by plug-ins to display a user manual for the plug-in.

    Plug-ins developers that wish to include help files should refer to this documentation in the Audacity wiki.

- LSP files may be used by a plug-in to provide additional code that is, or can be used by multiple plug-ins.

To install other supported file types (TXT, HTML, LSP), select the appropriate file type filter in the file browser.

Note that the only file type for a Nyquist plug-in is .NY. The other supported file types are copied to the user's plug-in folder so that the associated plug-in can access them, but do not need to be enabled in the Plug-In Manager, and do not appear in the Plug-In Manager.

Plug-in Developer Note:

  If a help file is included with a plug-in, it should be named in a manner to clearly show that it belongs with the plug-in. For example, if the plug-in is named "my-plug-in.ny", then the associated help file may be called "my-plug-in.html" or "my-plug-in-help.html".