mirror of
https://github.com/audacity/audacity-manual.git
synced 2025-12-16 04:22:00 -06:00
249 lines
18 KiB
HTML
249 lines
18 KiB
HTML
<!DOCTYPE html>
|
|
<html class="client-nojs" lang="en" dir="ltr">
|
|
<head>
|
|
<meta charset="UTF-8"/>
|
|
<title>Creating Nyquist Plugins - Audacity Manual</title>
|
|
|
|
|
|
|
|
|
|
|
|
<meta name="ResourceLoaderDynamicStyles" content=""/>
|
|
|
|
<meta name="generator" content="MediaWiki 1.28.2"/>
|
|
<link rel="shortcut icon" href="../favicon.ico"/>
|
|
<link rel="search" type="application/opensearchdescription+xml" href="https://alphamanual.audacityteam.org/m/opensearch_desc.php" title="Audacity Development Manual (en)"/>
|
|
<link rel="EditURI" type="application/rsd+xml" href="https://alphamanual.audacityteam.org/m/api.php?action=rsd"/>
|
|
<link rel="copyright" href="http://creativecommons.org/licenses/by/3.0/"/>
|
|
|
|
<link rel="stylesheet" href="../m/skins/monobook/main.css/303.css" media="screen" />
|
|
</head>
|
|
<body class="mediawiki ltr sitedir-ltr mw-hide-empty-elt ns-0 ns-subject page-Creating_Nyquist_Plug-ins rootpage-Creating_Nyquist_Plug-ins skin-monobook action-view"><div id="globalWrapper">
|
|
<div id="column-content">
|
|
<div id="content" class="mw-body" role="main">
|
|
<a id="top"></a>
|
|
|
|
<div class="mw-indicators">
|
|
</div>
|
|
<h1 id="firstHeading" class="firstHeading" lang="en">Creating Nyquist Plugins</h1>
|
|
|
|
<div id="bodyContent" class="mw-body-content">
|
|
<div id="siteSub">From Audacity Development Manual</div>
|
|
<div id="contentSub"></div>
|
|
<div id="jump-to-nav" class="mw-jump">Jump to: <a href="#column-one">navigation</a>, <a href="https://alphamanual.audacityteam.org/man/Creating_Nyquist_Plug-ins#searchInput">search</a></div>
|
|
|
|
|
|
<div id="mw-content-text" lang="en" dir="ltr" class="mw-content-ltr">
|
|
<div id="toc" class="toc"><div id="toctitle"><h2>Contents</h2></div>
|
|
<ul>
|
|
<li class="toclevel-1 tocsection-1"><a href="#Creating_Nyquist_Plugins"><span class="tocnumber">1</span> <span class="toctext">Creating Nyquist Plugins</span></a>
|
|
<ul>
|
|
<li class="toclevel-2 tocsection-2"><a href="#Parameter_dialogs"><span class="tocnumber">1.1</span> <span class="toctext">Parameter dialogs</span></a></li>
|
|
<li class="toclevel-2 tocsection-3"><a href="#Returning_labels"><span class="tocnumber">1.2</span> <span class="toctext">Returning labels</span></a></li>
|
|
<li class="toclevel-2 tocsection-4"><a href="#Processing_stereo_tracks"><span class="tocnumber">1.3</span> <span class="toctext">Processing stereo tracks</span></a></li>
|
|
<li class="toclevel-2 tocsection-5"><a href="#Where_to_go_from_here"><span class="tocnumber">1.4</span> <span class="toctext">Where to go from here</span></a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toclevel-1 tocsection-6"><a href="#Links"><span class="tocnumber">2</span> <span class="toctext">Links</span></a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
<h2><span class="mw-headline" id="Creating_Nyquist_Plugins">Creating Nyquist Plugins</span></h2>
|
|
<div style="margin-top:12px; margin-bottom:12px; margin-left:24px; margin-right:24px">
|
|
<table style="background:#FEFFD0; color:black; border:1px solid #999999; padding-left:12px; padding-right:12px" width="100%" align="center">
|
|
|
|
<tr>
|
|
<td width="30px" valign="top" align="center"><img alt="Advice" src="../m/images/b/ba/warningicon.png" title="Advice" width="24" height="24" />
|
|
</td>
|
|
<td align="left" valign="top">Do not attempt to use Windows NotePad or WordPad or any word processor for writing or editing Nyquist code. For Windows, <a rel="nofollow" class="external text" href="https://notepad-plus-plus.org/">Notepad++</a> is a good, free, plain text editor.
|
|
</td></tr></table></div>
|
|
<p>Creating a plugin for Audacity using Nyquist is as simple as creating a text file with the extension <b>.ny</b> with some Nyquist code, adding a few comments to indicate the type of plugin, and placing the file in Audacity's <b>Plug-Ins</b> directory. Here's a very simple plugin as an example:
|
|
</p>
|
|
<pre>
|
|
;nyquist plug-in
|
|
;version 4
|
|
;type process
|
|
;name "Fade In"
|
|
(mult (ramp) *track*)
|
|
</pre>
|
|
<p>The first line of a Nyquist plugin must be exactly as in the example above, and the second line must indicate a version number. Version 4 is the current version and should be used for all new code. The next line is the type of plugin, which is discussed below. Then comes the name of the plugin, which is what is displayed in the menu bar. There are other optional lines that may follow. Any line that does not begin with a semicolon (;) or a dollar sign ($) are assumed to contain Nyquist code and will be executed.
|
|
</p><p>Audacity has support for four types of plugins that can be written in Nyquist:
|
|
</p>
|
|
<pre>
|
|
;type generate
|
|
;type process
|
|
;type analyze
|
|
;type tool
|
|
</pre>
|
|
<p>These correspond to the four menus that can contain plugins: Generate, Effect, Analyze and Tools. Generate plugins are expected to generate new audio from scratch, Effect plugins modify existing audio in-place, and Analyze plugins process audio but do not modify it (though they are allowed to add labels). Tools are a special type for plugins that do not fall into any of the other three types (more information in the <a rel="nofollow" class="external text" href="https://plugins.audacityteam.org/nyquist-plugins/effect-plugins/time-pitch-and-tempo">Audacity Support site</a>).
|
|
</p><p>For Effect and Analyze plugins, Audacity sets up the Nyquist environment so that the audio the user has selected is in the variable <b>*track*</b> (in Nyquist before version 4, the variable <b>S</b> was used). All of the expressions in the plugin file are executed in order, and the return value of the last expression is substituted for the selection in Audacity. If the last expression does not return audio, Audacity returns an error.
|
|
</p>
|
|
<h3><span class="mw-headline" id="Parameter_dialogs">Parameter dialogs</span></h3>
|
|
<p>Audacity has limited support for plugins showing a dialog to get parameters from the user. Here is an example of a plugin that opens a dialog:
|
|
</p>
|
|
<pre>
|
|
;nyquist plug-in
|
|
;version 4
|
|
;type process
|
|
;name "Delay..."
|
|
;control decay "Decay amount" int "dB" 6 0 24
|
|
;control delay "Delay time" float "seconds" 0.5 0.0 5.0
|
|
;control count "Number of echos" int "times" 5 1 30
|
|
|
|
(defun delays (sig decay delay count)
|
|
(if (= count 0)
|
|
(cue sig)
|
|
(sim (cue sig)
|
|
(loud decay (at delay (delays sig decay delay (- count 1)))))))
|
|
|
|
(stretch-abs 1 (delays *track* (- 0 decay) delay count))
|
|
</pre>
|
|
<p>If Audacity finds at least one correctly formed "control" line, it will open a dialog to prompt the user for certain parameters to the plugin. Each control "widget" provides a variable (a symbol) that will store the value entered by the user. Here is what the dialog for the Delay effect shown above looks like (Windows 10):
|
|
</p>
|
|
<dl><dd><a href="https://alphamanual.audacityteam.org/man/File:Delay-demo-plug-in.png" class="image"><img alt="Delay-demo-plug-in.png" src="../m/images/b/b5/delay_demo_plug_in.png" width="533" height="191" /></a></dd></dl>
|
|
<h3><span class="mw-headline" id="Returning_labels">Returning labels</span></h3>
|
|
<p>Instead of returning audio, a Nyquist plugin can instead return a list of labels. A list of labels is simply a list of time/label pairs, for example:
|
|
</p>
|
|
<pre>
|
|
(list (list 0.0 "start")
|
|
(list 30.0 "middle")
|
|
(list 60.0 "end"))
|
|
</pre>
|
|
<p>When a plugin returns a list of exactly this form, Audacity will create a new label track and add the labels at those positions. The time value is in seconds. This style of plugin is usually of type "analyze".
|
|
</p><p>To create <a href="label_tracks.html#type" title="Label Tracks">region labels</a> there needs to be two time values:
|
|
</p>
|
|
<pre>
|
|
(list (list 0.0 25.0 "start")
|
|
(list 30.0 45.0 "middle")
|
|
(list 60.0 75.0 "end"))
|
|
</pre>
|
|
<p>Note that labels are allowed to overlap, the end time of one can be after the start time of the next.
|
|
</p>
|
|
<h3><span class="mw-headline" id="Processing_stereo_tracks">Processing stereo tracks</span></h3>
|
|
<p>Nyquist represents stereo tracks as an array of sounds (not a list). Many Nyquist functions automatically work with these arrays, but not all, so sometimes you may find it necessary to split up a stereo array, or reassemble one. Here are some useful functions:
|
|
</p><p><br />
|
|
</p>
|
|
<table style="border-spacing:0; width: 50em;">
|
|
<tr>
|
|
<td style="border-top:0.05pt solid #000000;border-bottom:0.05pt solid #000000;border-left:0.05pt solid #000000;border-right:none;padding:0.049cm;"> <tt><b>(arrayp *track*)</b></tt>
|
|
</td>
|
|
<td style="border-top:0.05pt solid #000000;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;"> returns true if <b>*track*</b> is an array
|
|
</td></tr>
|
|
<tr>
|
|
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:0.05pt solid #000000;border-right:none;padding:0.049cm;"> <tt><b>(aref *track* 0)</b></tt>
|
|
</td>
|
|
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;"> the first element in array <b>*track*</b> \xe2\x80\x93 the left channel
|
|
</td></tr>
|
|
<tr>
|
|
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:0.05pt solid #000000;border-right:none;padding:0.049cm;"> <tt><b>(aref *track* 1)</b></tt>
|
|
</td>
|
|
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;"> the second element in array <b>*track*</b> \xe2\x80\x93 the right channel
|
|
</td></tr>
|
|
<tr>
|
|
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:0.05pt solid #000000;border-right:none;padding:0.049cm;"> <tt><b>(setf my-array (make-array 2))</b></tt>
|
|
</td>
|
|
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;"> makes <b>my-array</b> into a new array of length 2
|
|
</td></tr>
|
|
<tr>
|
|
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:0.05pt solid #000000;border-right:none;padding:0.049cm;"> <tt><b>(setf (aref my-array 0) left)</b></tt>
|
|
</td>
|
|
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;"> makes <b>left</b> the first element of array <b>my-array</b>
|
|
</td></tr>
|
|
<tr>
|
|
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:0.05pt solid #000000;border-right:none;padding:0.049cm;"> <tt><b>(setf (aref my-array 1) right)</b></tt>
|
|
</td>
|
|
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;"> makes <b>right</b> the second element of array <b>my-array</b>
|
|
</td></tr></table>
|
|
<p>As a convenience, if the input to your Nyquist plugin is stereo, but you only output a single (mono) sound, Audacity will automatically copy it to both the left and right channels.
|
|
</p>
|
|
<h3><span class="mw-headline" id="Where_to_go_from_here">Where to go from here</span></h3>
|
|
<p>Audacity comes with some sample plugins that you can examine or modify as a starting point. The best way to learn Nyquist is to try it.
|
|
</p><p>See: <a rel="nofollow" class="external text" href="https://plugins.audacityteam.org/contributing/developing-your-own-plugins-and-scripts/creating-your-own-nyquist-plugins"><b>Creating your own Nyquist Plugins</b></a> in the Audacity Support site.
|
|
</p><p>Technical support is provided on the <a rel="nofollow" class="external text" href="https://forum.audacityteam.org/viewforum.php?f=39"><b>Nyquist board of the Audacity Forum</b></a> (email registration required for posting).
|
|
</p>
|
|
<h2><span class="mw-headline" id="Links">Links</span></h2>
|
|
<p><a href="programming_in_nyquist.html" title="Programming in Nyquist"><b><</b>  Programming in Nyquist</a> <br />
|
|
</p><p><a href="nyquist.html" title="Nyquist"><b>|<</b> Nyquist</a>
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
<div class="visualClear"></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div id="column-one">
|
|
|
|
|
|
|
|
<div class="portlet" id="p-logo" role="banner">
|
|
<a href="../index.html" class="mw-wiki-logo" title="Visit the main page"></a>
|
|
</div>
|
|
|
|
<div class="generated-sidebar portlet" id="p-Navigation" role="navigation">
|
|
<h3>Navigation</h3>
|
|
<div class='pBody'>
|
|
<ul><li> <a href="../index.html" title="Main Page"><span title="Front page, complete with clickable image of Audacity screen.">Manual Home Page</span></a>
|
|
<ul><li> <a href="audacity_tour_guide.html" title="Audacity Tour Guide"><span title="A quick tour of selected features of Audacity. It doesn't tell you how to use features it would be much too long if it did. Rather it tells you about some of the features that exist in Audacity and will help you learn a little about those.">Tour Guide</span></a></li></ul></li>
|
|
<li> <a href="how_to_use_audacity.html" title="How to use Audacity"><span title="Quick Help, Audacity Foundations, Editing with Audacity, Help with Advanced Topics">Using Audacity</span></a>
|
|
<ul><li> <a href="../quick_help.html" title="Quick Help"><span title="A brief guide to help you get started with Audacity">Getting Started</span></a></li>
|
|
<li> <a href="how_to_use_audacity.html" title="How to use Audacity"><span title="A comprehensive guide to using Audacity">How-Tos</span></a></li>
|
|
<li> <a href="tutorials_for_audacity.html" title="Tutorials for Audacity"><span title="A guide to the tutorials that provide step-by-step instructions for performing common tasks in Audacity">Tutorials</span></a></li>
|
|
<li> <a href="tips.html" title="Tips"><span title="A guide to particular aspects of working with Audacity: Navigation. Playback, Audio Alignment">Tips</span></a></li></ul></li>
|
|
<li> <a href="../index.html#reference" title="Main Page"><span title="The components of the Audacity Graphical User Interface">Audacity GUI</span></a>
|
|
<ul><li> <a href="menu_reference.html" title="Menu Reference"><span title="A guide to the menus and submenus in Audacity">Menu Bar</span></a></li>
|
|
<li> <a href="toolbars_overview.html" title="Toolbars Overview"><span title="A guide to the various Toolbars used in Audacity">Toolbars</span></a></li>
|
|
<li> <a href="audio_tracks.html" title="Audio Tracks"><span title="A guide to the various types of track">Tracks</span></a></li>
|
|
<li> <a href="index_of_effects_generators_and_analyzers.html" title="Index of Effects, Generators and Analyzers"><span title="A quick index to the Effects, Generators and Analyzers that are shipped with Audacity">Effects</span></a></li></ul></li>
|
|
<li> <a href="customization.html" title="Customization"><span title="Adjust settings, change keyboard shortcuts, add plugins">Customizing</span></a>
|
|
<ul><li> <a href="preferences.html" title="Preferences"><span title="A guide to Preferences, which let you change most of the default behaviors of Audacity">Preferences</span></a></li>
|
|
<li> <a href="keyboard_shortcut_reference.html" title="Keyboard Shortcut Reference"><span title="A list of all the commands in the Audacity menus and all pre-defined keyboard shortcuts">Shortcut keys</span></a></li>
|
|
<li> <a href="customization.html#plugins" title="Customization"><span title="You can download and install plugins to add extra functionality to Audacity. Plugins can give you extra effects, or more audio generation and analysis capability.">Plugins</span></a></li>
|
|
<li> <a href="themes.html" title="Themes"><span title="Audacity now comes supplied with four pre-configured, user-selectable themes. This enables you to choose the look and feel you prefer for Audacity's interface.">Themes</span></a></li>
|
|
<li> <a href="customizing_toolbar_layout.html" title="Customizing Toolbar Layout"><span title="Audacity's toolbars can all be re-positioned (in the tooldocks or free-floating) and some can be resized.">Toolbars</span></a></li>
|
|
<li> <a href="manage_effects_generators_and_analyzers.html" title="Manage Effects, Generators and Analyzers"><span title="Manage your list of available built-in Effects, Generators, Analyzers and plugins with the Plugin Manager">Effects</span></a></li></ul></li></ul>
|
|
</div>
|
|
</div>
|
|
<div class="generated-sidebar portlet" id="p-Reference" role="navigation">
|
|
<h3>Reference</h3>
|
|
<div class='pBody'>
|
|
<ul><li> <a href="../index.html#reference" title="Main Page"><span title="Reference guide to the Audacity project window - you can hover over and click on the image to learn more">Reference</span></a>
|
|
<ul><li> <a href="searching_the_manual.html" title="Searching the Manual"><span title="Tips on how to Search the Audacity Manual">Search the Manual</span></a></li>
|
|
<li> <a href="digital_audio.html" title="Digital Audio"><span title="A beginner's guide to digital audio">Digital Audio</span></a></li>
|
|
<li> <a href="glossary.html" title="Glossary"><span title="Brief explanations of technical terms related to digital audio, with some links to Wikipedia for much more comprehensive explanations">Glossary</span></a></li>
|
|
<li> <a href="scripting_reference.html" title="Scripting Reference"><span title="Audacity Commands that are in menus, that can be used from Macros, Nyquist and Python">All Commands</span></a></li>
|
|
<li> <a href="faq_errors.html" title="FAQ:Errors"><span title="FAQ on common errors encountered when using Audacity">Errors</span></a></li>
|
|
<li> <a href="subject_index.html" title="Subject Index"><span title="A short, limited, index of the Manual">Index</span></a></li></ul></li>
|
|
<li> <a href="faq.html" title="FAQ"><span title="Frequently Asked Questions - most common questions are answered in the FAQ">FAQ</span></a></li></ul>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="generated-sidebar portlet" id="p-Useful_Links" role="navigation">
|
|
<h3>Useful Links</h3>
|
|
<div class='pBody'>
|
|
<ul><li> <span title="Audacity Forum (best place for support requests)"><a rel="nofollow" class="external text" href="https://forum.audacityteam.org/">Forum</a></span></li>
|
|
<li> <span title="Audacity Wiki Home Page"><a rel="nofollow" class="external text" href="https://support.audacityteam.org/">Audacity Support</a></span></li>
|
|
<li> <span title="Audacity Latest Release"><a rel="nofollow" class="external text" href="https://www.audacityteam.org/download/">Latest Release</a></span></li></ul>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
<div class="visualClear"></div>
|
|
<div id="footer" role="contentinfo">
|
|
<div id="f-copyrightico">
|
|
|
|
</div>
|
|
<div id="f-poweredbyico">
|
|
<a href="https://www.mediawiki.org/"><img src="../m/resources/assets/poweredby_mediawiki_88x31.png" alt="Powered by MediaWiki" srcset="/m/resources/assets/poweredby_mediawiki_132x47.png 1.5x, /m/resources/assets/poweredby_mediawiki_176x62.png 2x" width="88" height="31"/></a>
|
|
</div>
|
|
|
|
<div align="center"><ul id="f_list"><li>This version created on 2025-12-04 - <a href="https://alphamanual.audacityteam.org/man/Creating_Nyquist_Plug-ins">Check current version of this page (development Manual)</a></li></ul></div>
|
|
</div>
|
|
</div>
|
|
</body></html>
|