audacity-manual/manual/man/programming_in_nyquist.html
2025-12-04 12:24:42 +00:00

266 lines
22 KiB
HTML

<!DOCTYPE html>
<html class="client-nojs" lang="en" dir="ltr">
<head>
<meta charset="UTF-8"/>
<title>Programming in Nyquist - 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-Programming_in_Nyquist rootpage-Programming_in_Nyquist 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">Programming in Nyquist</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/Programming_in_Nyquist#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="#Programming_in_Nyquist"><span class="tocnumber">1</span> <span class="toctext">Programming in Nyquist</span></a>
<ul>
<li class="toclevel-2 tocsection-2"><a href="#Synthesizing"><span class="tocnumber">1.1</span> <span class="toctext">Synthesizing</span></a></li>
<li class="toclevel-2 tocsection-3"><a href="#Combining_sounds"><span class="tocnumber">1.2</span> <span class="toctext">Combining sounds</span></a></li>
<li class="toclevel-2 tocsection-4"><a href="#Filters"><span class="tocnumber">1.3</span> <span class="toctext">Filters</span></a></li>
<li class="toclevel-2 tocsection-5"><a href="#Transforming_and_combining_sounds"><span class="tocnumber">1.4</span> <span class="toctext">Transforming and combining sounds</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="Programming_in_Nyquist">Programming in Nyquist</span></h2>
<p>What makes Nyquist distinct from Lisp is that it is designed to work with sound, and has lots of built-in primitives and functions that synthesize, analyze, and manipulate sounds. Within Audacity, this makes it relatively easy to build complicated effects out of Nyquist's palette of built-in functions.
</p><p>In Nyquist, a variable can hold a sound just as easily as it can hold a number or a string. There are a lot of functions provided that allow you to stretch, distort, and combine sounds very efficiently. It is even possible to "rip apart" a sound and access its individual samples, but that is beyond the scope of this tutorial.
</p><p>To try out a Nyquist expression in Audacity, you can use <a href="nyquist_prompt.html" title="Nyquist Prompt">Nyquist Prompt</a> in the Effect menu. Whatever audio you have selected will be in the variable <span style="line-height:1.1em;letter-spacing:-0.04em;background-color:#FDEEF4;padding:3px;font-family:monospace;font-size:1.1em;border:1px dashed black">*track*</span>, and the selection will be replaced with the result of the Nyquist expression you enter. In Part 3: <a href="creating_nyquist_plug_ins.html" title="Creating Nyquist Plug-ins">Creating Nyquist Plugins</a>, you will learn how to create a plugin effect using Nyquist.
</p>
<h3><span class="mw-headline" id="Synthesizing">Synthesizing</span></h3>
<p>The following functions all create new sounds. You can use them to create "generate" plugin effects, or you can combine these synthesized sounds with selected audio to produce interesting effects.
</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;"> <b>(noise)</b>
</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;"> Generates white noise
</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;"> <b>(const value [duration])</b>
</td>
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;"> Generates a constant (silent) signal
</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;"> <b>(sine pitch [duration])</b>
</td>
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;"> Generates a sine wave at an indicated pitch and duration.The pitch is a MIDI note number, with 60 for middle C.
</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;"> <b>(hzosc hz)</b>
</td>
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;"> Generates a sine wave at a particular frequency in Hz.
</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;"> <b>(osc-saw hz)</b>
</td>
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;"> Generates a sawtooth wave at a particular frequency in Hz.
</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;"> <b>(osc-tri hz)</b>
</td>
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;"> Generates a triangle wave at a particular frequency in Hz.
</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;"> <b>(osc-pulse hz bias)</b>
</td>
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;">
</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;"> <b>(pluck pitch)</b>
</td>
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;">
</td></tr></table>
<p><b>Envelopes</b>
</p><p>Nyquist has support for envelopes. By applying an envelope to a sound, you can control the overall shape of its amplitude. One of the easiest ways to construct an envelope is with the <span style="line-height:1.1em;letter-spacing:-0.04em;background-color:#FDEEF4;padding:3px;font-family:monospace;font-size:1.1em;border:1px dashed black">env</span> function, which takes 7 parameters that are commonly used for shaping synthesized musical notes: attack time, decay time, release time, attack level, decay level, sustain level, and overall duration.See the figure below:
</p><p><a href="https://alphamanual.audacityteam.org/man/File:Nyquist-envelope.gif" class="image"><img alt="Nyquist-envelope.gif" src="../m/images/d/d9/nyquist_envelope.gif" width="467" height="200" /></a>
</p><p>To apply an envelope to a sound, just use the <span style="line-height:1.1em;letter-spacing:-0.04em;background-color:#FDEEF4;padding:3px;font-family:monospace;font-size:1.1em;border:1px dashed black">mult</span> function. So if <span style="line-height:1.1em;letter-spacing:-0.04em;background-color:#FDEEF4;padding:3px;font-family:monospace;font-size:1.1em;border:1px dashed black">*track*</span> is the sound, then this is the sound with a simple envelope applied to it:
</p>
<pre> (mult *track* (env 0.1 0.1 0.2 1.0 0.5 0.3 1.0))
</pre>
<p>One of the most general type of envelope is a piece-wise linear function, which can be constructed with the <span style="line-height:1.1em;letter-spacing:-0.04em;background-color:#FDEEF4;padding:3px;font-family:monospace;font-size:1.1em;border:1px dashed black">pwl</span> function. The pwl function takes a list of parameters which denote (time, value) pairs. There is an implicit initial (time, value) pair of (0, 0), and an implicit final value of 0. There should always be an odd number of parameters, since the final time is not implicit. For example:
</p>
<pre> ; symmetric rise to 0.7 (at time 1) and fall back to 0 (at time 2):
(pwl 1.0 0.7 2.0)
</pre>
<h3><span class="mw-headline" id="Combining_sounds">Combining sounds</span></h3>
<p>Besides multiplying two sounds with the <span style="line-height:1.1em;letter-spacing:-0.04em;background-color:#FDEEF4;padding:3px;font-family:monospace;font-size:1.1em;border:1px dashed black">mult</span> function, you can add two sounds (or envelopes) with the <span style="line-height:1.1em;letter-spacing:-0.04em;background-color:#FDEEF4;padding:3px;font-family:monospace;font-size:1.1em;border:1px dashed black">add</span> function.
</p>
<h3><span class="mw-headline" id="Filters">Filters</span></h3>
<p>Nyquist comes with a number of common filters built-in. Here are some of the more common ones:
</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;"> <b>(lp sound cut-off)</b>
</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;">
</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;"> <b>(hp sound cut-off)</b>
</td>
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;"> High-pass filter (first-order Butterworth). Cut-off may be a float or a signal (for time-varying filtering) and expresses hertz.
</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;"> <b>(comb sound hz decay)</b>
</td>
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;"> Applies a comb filter to sound, which emphasizes (resonates at) frequencies that are multiples of a Hz.
</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;"> <b>(alpass sound decay hz)</b>
</td>
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;"> All-pass filter, creating a delay effect without the resonances of a comb filter.
</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;"> <b>(notch2 sound hz)</b>
</td>
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;">
</td></tr></table>
<h3><span class="mw-headline" id="Transforming_and_combining_sounds">Transforming and combining sounds</span></h3>
<p>It is beyond the scope of this introductory tutorial to explain all of the ways that a sound can be transformed in Nyquist. These functions do not modify sounds directly, but instead modify the Nyquist <i>environment</i>. In order for these changes to affect sounds, you must use the <span style="line-height:1.1em;letter-spacing:-0.04em;background-color:#FDEEF4;padding:3px;font-family:monospace;font-size:1.1em;border:1px dashed black">cue</span> function.
</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;"> <b>(stretch factor (cue sound))</b>
</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;"> Changes the length of the sound being cued by the given factor.
</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;"> <b>(scale factor (cue sound))</b>
</td>
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;"> Scales the amplitude of the sound being cued by the given factor.
</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;"> <b>(loud dB (cue sound))</b>
</td>
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;"> Increases or decreases the volume of the sound being cued by the given number of decibels.
</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;"> <b>(at t (cue sound))</b>
</td>
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;"> Starts the given sound at a particular time in seconds. This cannot be used to add silence at the beginning or end, but it can be used when combining two or more sounds.
</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;"> <b>(seq (cue s1) (cue s2))</b>
</td>
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;"> Creates a sequence of sound s1 followed by sound s2.
</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;"> <b>(sim (cue s1) (cue s2))</b>
</td>
<td style="border-top:none;border-bottom:0.05pt solid #000000;border-left:none;border-right:0.05pt solid #000000;padding:0.049cm;"> Combines two sounds so that they are played simultaneously.
</td></tr></table>
<h2><span class="mw-headline" id="Links">Links</span></h2>
<p><a href="creating_nyquist_plug_ins.html" title="Creating Nyquist Plug-ins"><b>&gt;</b>&#160; Creating Nyquist Plugins</a> <br />
</p><p><a href="introduction_to_nyquist_and_lisp_programming.html" title="Introduction to Nyquist and Lisp Programming"><b>&lt;</b>&#160; Introduction to Nyquist and Lisp Programming</a> <br />
</p><p><a href="nyquist.html" title="Nyquist"><b>|&lt;</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&#39;s interface.">Themes</span></a></li>
<li> <a href="customizing_toolbar_layout.html" title="Customizing Toolbar Layout"><span title="Audacity&#39;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&#39;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/Programming_in_Nyquist">Check current version of this page (development Manual)</a></li></ul></div>
</div>
</div>
</body></html>